\n\nPostman collection for all HBDRP Integration API endpoints — birth & death registration, authentication, status lookups, and real-time callback events for third-party systems.
\n
When a third-party system submits a birth or death record, a unique document number is always generated and returned immediately in the API response — regardless of the record's status. This document number is the record's identifier and is used to track its current state throughout the flow.
\nFrom there, the record moves through review → verification → registration → approval & numbering → certification before it is final. At every stage change after submission:
\ncallback_urlSteps 2 through 6 each fire a callback event. Step 1 (Submitted) fires no callback — the document number is returned directly in the API response.
\nThere are exactly six callback events, and no others: MARKED_COMPLETE, VERIFIED, DUPLICATE_REJECTED, PUSHED_TO_REGISTRATION, COMPLETED, CERTIFIED.
Submitted\n |\n ▼\nOfficer Review .......... (MARKED_COMPLETE)\n |\n ▼\nDuplicate Verification .. (VERIFIED ✔ / DUPLICATE_REJECTED ✗)\n |\n ▼\nPushed to Registration .. (PUSHED_TO_REGISTRATION)\n |\n ▼\nApproval & Numbering .... (COMPLETED)\n |\n ▼\nCertification ........... (CERTIFIED ★ terminal success)\n\n\n⚠️
\nDUPLICATE_REJECTEDends the flow — the record does not continue to registration.
COMPLETED means the record has passed all approval levels and the registration number / UBNC has been generated. It does not mean a certificate has been issued. At this point the certification record exists but is still pending.CERTIFIED is the terminal success event. It fires later, when the certifying officer formally issues the certificate. Integrators expecting a final \"certificate issued\" signal must listen for CERTIFIED, not COMPLETED.COMPLETED and CERTIFIED carry registration_no, ubnc and certificate_number — these three fields always hold the same value.APPROVED is not a callback event and is never sent to your callback_url. It appears only as a polling stage returned by the status lookup endpoint. Use the COMPLETED callback to be notified of this stage.Status can always be checked directly via:
\nGET /integrations/registrations/birth/{documentNumber}GET /integrations/registrations/death/{documentNumber}POSTed to the institution's configured callback_url.Content-Type, Accept, X-Event-Type, X-Document-Number, X-Timestamp.\n\n📁 See the \"Callback Events Documentation\" folder (under BETA) for the full flow reference — including the complete event table, callback delivery requirements, and a step-by-step breakdown of each stage.
\n
Create a new environment in Postman and add the following variables:
\nIntegration APIs (Third-Party)
\nMiddleware: apiConsumer — automatically injects user_id and source_institution_code.
All requests require:
\nContent-Type: application/json\nAccept: application/json\nToken: your-token-here\n# — or —\nAuthorization: Bearer your-token-here\n\n\nFor Integration APIs, use the
\naccess_tokenwhen using the token-refresh flow.
REGION · DISTRICT · REGISTRY · TOWN · NATIONAL_ID · GENDER · MARITAL_STATUS · EDUCATIONAL_LEVEL · RELIGION · NATIONALITY · INFORMANT_TYPE · BIRTH_TYPE · BIRTH_ATTENDANT · PLACE_OF_BIRTH
For additional support, please contact our support team.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"HBDRP Integration API","slug":"hbdrp-integration-api"}],"owner":"26097188","collectionId":"13f20a0b-9bf3-4c28-870e-bb97d149f666","publishedId":"2sB2qZE2N9","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-05-20T17:13:19.000Z"},"item":[{"name":"BETA","item":[{"name":"Auth (Token & Refresh)","item":[{"name":"Get Access Token","id":"5fc33b1a-d56f-45ab-b029-212993976580","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"your-token-here"}]},"isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{}","options":{"raw":{"language":"json"}}},"url":"https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/auth/token","description":"POST https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/auth/token
Exchanges your long-lived API-consumer token for a short-lived access token (and a refresh token). Send your API token in the Token header (or Authorization: Bearer <api_token>). The request body is empty ({}).
Returns an access_token and a refresh_token.
access_token expires in 60 minutes — use it as the Token on registration/utility requests.refresh_token — pass to the Refresh Token request to get a new pair without re-sending your long-lived token.Tip: save access_token and refresh_token to your environment after this call so downstream requests pick them up automatically.
POST https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/auth/refresh
Exchanges a valid refresh token for a new access_token / refresh_token pair, so you can keep calling the API after the 60-minute access token expires — without re-sending your long-lived API-consumer token.
{ \"refresh_token\": \"{{refresh_token}}\" }\nNo additional auth header is required — the refresh_token in the body is the credential.
Returns a new access_token (valid 60 minutes) and a new refresh_token. Save both to your environment; the previous refresh token should be considered rotated/invalid after use.
Every third-party integration call is authenticated with a short-lived access token. You start from a long-lived API-consumer token (issued to you during setup) and exchange it for an access/refresh token pair. This folder contains the two endpoints that manage that lifecycle.
\naccess_token and refresh_token (e.g. in your Postman environment).access_token as the Token header on all registration, utility, and record-lookup requests.refresh_token to rotate to a fresh pair — without re-sending your long-lived token.refresh_token should be treated as rotated/invalid.GET /integrations/registrations/birth/{documentNumber}
Returns the current state and callback history of a birth record. Use this to poll a record's progress at any time.
\nThe process_flow.current_stage field returns one of:
SUBMITTED, DRAFT, PENDING_REVIEW, MARKED_COMPLETE, IN_VERIFICATION, VERIFIED, DUPLICATE_REJECTED, IN_REGISTRATION, APPROVED, CERTIFIED
\n\n\n
APPROVEDappears here as a polling stage only — it is never delivered as a webhook. Use theCOMPLETEDcallback to be notified of this stage.
process_flow.stages.certification.is_certified is false while the record is approved but not yet certified, and becomes true once the certificate has been issued.
The callback_history array lists every callback event that has been dispatched for the record, each with its event_type, callback_status and timestamp.
API consumer token
\n","type":"text"}],"body":{"mode":"raw","raw":"{\n // status controls validation depth:\n // DRAFT -> saved as-is; return status is PENDING; only status/region_id/district_id enforced; editable via the update endpoint.\n // COMPLETE -> full validation of every REQUIRED field below before it moves to verification/approval/certification.\n // Early vs Late birth is auto-determined from child_dob (under 1yr => Early Birth, 1yr or older => Late Birth). Do not send it.\n \"status\": \"COMPLETE\", // REQUIRED (DRAFT | COMPLETE)\n\n \"region_id\": 4348, // utility_type=REGION (REQUIRED for third-party integrations)\n \"district_id\": 338, // utility_type=DISTRICT (REQUIRED for third-party integrations) -- must belong to region_id\n \n \"type_of_birth\": \"SINGLETON\", // utility_type=BIRTH_TYPE // REQUIRED\n\n \"informant_type\": \"MOTHER\", // utility_type=INFORMANT_TYPE // REQUIRED\n \"informant_national_id_type\": \"GHANA CARD\", // utility_type=NATIONAL_ID // REQUIRED\n \"informant_national_id_number\": \"34454344\", // REQUIRED (alphanumeric + hyphen, max 20)\n \"informant_first_name\": \"David\", // REQUIRED\n \"informant_middle_name\": \"\", // OPTIONAL\n \"informant_last_name\": \"Godson\", // REQUIRED\n \"informant_region_id\": 4348, // utility_type=REGION // OPTIONAL (if both region+district sent, district must match region)\n \"informant_district_id\": 338, // utility_type=DISTRICT // OPTIONAL\n \"informant_residential_address\": \"Dansoman\", // REQUIRED (max 300)\n \"informant_phone_number\": \"2335648498309\", // REQUIRED (phone ^(\\+)?[0-9]{10,}$)\n\n \"child_first_name\": \"Gideon\", // REQUIRED (blacklist-checked)\n \"child_middle_name\": \"\", // OPTIONAL\n \"child_last_name\": \"Oduro\", // REQUIRED (blacklist-checked)\n \"child_gender\": \"MALE\", // utility_type=GENDER // REQUIRED\n \"child_dob\": \"2026-04-05\", // REQUIRED (date YYYY-MM-DD, not future; determines Early/Late birth)\n \"child_national_id_type\": \"\", // utility_type=NATIONAL_ID // OPTIONAL\n \"child_national_id_number\": \"\", // OPTIONAL (alphanumeric + hyphen, max 20)\n \"child_place_of_birth\": \"HOSPITAL\", // utility_type=PLACE_OF_BIRTH // REQUIRED\n \"child_birth_attendant\": \"MID-WIFE\", // utility_type=BIRTH_ATTENDANT // REQUIRED\n \"child_birth_institution\": \"Ludra Hospital\", // REQUIRED (max 500)\n \"child_town\": \"Ashaiman\", // utility_type=TOWN // REQUIRED\n \"child_house_no\": \"H/F286\", // OPTIONAL\n \"child_street_name\": \"Ashaiman Newtown\", // OPTIONAL\n\n \"mother_national_id_type\": \"GHANA CARD\", // utility_type=NATIONAL_ID // CONDITIONAL: required if mother is non-Ghanaian\n \"mother_national_id_number\": \"32432423433\", // CONDITIONAL: required if mother is non-Ghanaian (alphanumeric + hyphen, max 20)\n \"mother_phone_number\": \"2335456823893\", // CONDITIONAL: required unless doubtful_maternity=1 (phone ^(\\+)?[0-9]{10,}$)\n \"mother_first_name\": \"Adwoa\", // CONDITIONAL: required unless doubtful_maternity=1\n \"mother_middle_name\": \"\", // OPTIONAL\n \"mother_last_name\": \"Godson\", // CONDITIONAL: required unless doubtful_maternity=1\n \"mother_age\": 30, // CONDITIONAL: required unless doubtful_maternity=1 (11-70)\n \"mother_marital_status\": \"MARRIED\", // utility_type=MARITAL_STATUS // CONDITIONAL: required unless doubtful_maternity=1\n \"mother_previous_birth_no\": 50, // CONDITIONAL: required unless doubtful_maternity=1 (max 50)\n \"mother_occupation\": \"teacher\", // CONDITIONAL: required unless doubtful_maternity=1\n \"mother_educational_level\": \"DIPLOMA\", // utility_type=EDUCATIONAL_LEVEL // CONDITIONAL: required unless doubtful_maternity=1\n \"mother_region_id\": 4348, // utility_type=REGION // OPTIONAL\n \"mother_district_id\": 338, // utility_type=DISTRICT // OPTIONAL\n \"mother_town\": \"Accra\", // utility_type=TOWN // OPTIONAL\n \"mother_religion\": \"CHRISTIAN\", // utility_type=RELIGION // OPTIONAL\n \"mother_residence\": \"Tamale\", // CONDITIONAL: required unless doubtful_maternity=1\n \"mother_nationality\": \"GHANA\", // utility_type=NATIONALITY // CONDITIONAL: required unless doubtful_maternity=1\n \"doubtful_maternity\": 0, // OPTIONAL (0/1; set 1 to skip mother requirements)\n \n \"father_national_id_type\": \"GHANA CARD\", // utility_type=NATIONAL_ID // CONDITIONAL: required if father is non-Ghanaian\n \"father_national_id_number\": \"32432423433\", // CONDITIONAL: required if father is non-Ghanaian (alphanumeric + hyphen, max 20)\n \"father_phone_number\": \"233548791223\", // CONDITIONAL: required unless doubtful_paternity=1 (phone ^(\\+)?[0-9]{10,}$)\n \"father_first_name\": \"David\", // CONDITIONAL: required unless doubtful_paternity=1\n \"father_middle_name\": \"\", // OPTIONAL\n \"father_last_name\": \"Oduro\", // CONDITIONAL: required unless doubtful_paternity=1\n \"father_age\": 33, // CONDITIONAL: required unless doubtful_paternity=1 (11-80)\n \"father_marital_status\": \"MARRIED\", // utility_type=MARITAL_STATUS // CONDITIONAL: required unless doubtful_paternity=1\n \"father_children_no\": 5, // CONDITIONAL: required unless doubtful_paternity=1 (max 50)\n \"father_occupation\": \"Doctor\", // CONDITIONAL: required unless doubtful_paternity=1\n \"father_educational_level\": \"DIPLOMA\", // utility_type=EDUCATIONAL_LEVEL // CONDITIONAL: required unless doubtful_paternity=1\n \"father_region_id\": 4348, // utility_type=REGION // OPTIONAL\n \"father_district_id\": 338, // utility_type=DISTRICT // OPTIONAL\n \"father_town\": \"Tema\", // utility_type=TOWN // OPTIONAL\n \"father_residence\": \"Tema\", // CONDITIONAL: required unless doubtful_paternity=1\n \"father_nationality\": \"GHANA\", // utility_type=NATIONALITY // CONDITIONAL: required unless doubtful_paternity=1\n \"father_religion\": \"CHRISTIAN\", // utility_type=RELIGION // CONDITIONAL: required unless doubtful_paternity=1\n \"doubtful_paternity\": 0, // OPTIONAL (0/1; set 1 to skip father requirements)\n \n \"child_file_birth_evidence_name\": [\"Physics.jpg\"], // OPTIONAL (array of file names; PDF/JPG/PNG)\n \"child_file_birth_evidence_data\": [\"data:image/jpeg;base64,/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAAAAAAAP/sABFEdWNreQABAAQAAAA8AAD/4QOJaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLwA8P3hwYWNrZXQgYmVnaW49Iu+7vyIgaWQ9Ilc1TTBNcENlaGlIenJlU3pOVGN6a2M5ZCI/PiA8eDp4bXBtZXRhIHhtbG5zOng9ImFkb2JlOm5zOm1ldGEvIiB4OnhtcHRrPSJBZG9iZSBYTVAgQ29yZSA1LjYtYzEzOCA3OS4xNTk4MjQsIDIwMTYvMDkvMTQtMDE6MDk6MDEgICAgICAgICI=\" // OPTIONAL (array of base64 data: URLs; PDF/JPG/PNG)\n ]\n // SYSTEM-SET (do not send): created_by, third_party_user_id, registry_id, document_number\n}\n","options":{"raw":{"language":"json"}}},"url":"https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/registrations/birth","description":"POST https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/registrations/birth
Creates a new birth registration record for third-party integrations. Authenticate with your API-consumer Token header.
\nstatus = DRAFT — saved as-is (return status PENDING); only status, region_id, district_id are enforced. Editable later via the update endpoint.status = COMPLETE — every Required field below is validated before the record moves to verification, approval & certification.child_dob (under 1 year → Early Birth; 1 year or older → Late Birth). Do not send it.Field status below matches the third-party field reference exactly (COMPLETE validation).
\nRequired unless doubtful_maternity=1. If the mother is non-Ghanaian, her national-ID fields also become required.
Same pattern as mother, keyed on doubtful_paternity and the father's nationality.
These are taken from your token or assigned automatically; sending them has no effect:
\ncreated_bythird_party_user_idregistry_id (auto-assigned round-robin among active registries in the submitted district)document_number (generated on create; passed back in the URL to update)Fields marked coded accept only values that exist in the system's reference tables and are case/spelling sensitive. Fetch the allowed values from the utilities endpoint before submitting (by utility_type): REGION, DISTRICT, TOWN, GENDER, INFORMANT_TYPE, NATIONAL_ID, PLACE_OF_BIRTH, BIRTH_ATTENDANT, MARITAL_STATUS, EDUCATIONAL_LEVEL, RELIGION, NATIONALITY, BIRTH_TYPE.
region_id / district_id are numeric IDs; the district must belong to the region.\"MALE\", \"MARRIED\".{\n \"status\": \"DRAFT\",\n \"region_id\": 1,\n \"district_id\": 1\n}\nPOST https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/registrations/birth/{{documentNumber}}
Updates an existing birth registration record identified by documentNumber in the URL. Authenticate with your API-consumer Token header. The body uses the same fields and validation rules as Create Birth Record; you re-submit the full record for the document you are updating.
status = DRAFT — saved as-is (return status PENDING); only status, region_id, district_id are enforced. A DRAFT can be updated repeatedly while you gather data.status = COMPLETE — every Required field below is validated before the record moves to verification, approval & certification. Typical flow: submit DRAFT first, then re-submit the same documentNumber with COMPLETE once everything is filled in.child_dob (under 1 year → Early Birth; 1 year or older → Late Birth). Do not send it.documentNumber is passed in the URL path (not the body) to identify the record.Field status below matches the third-party field reference exactly (COMPLETE validation).
\nRequired unless doubtful_maternity=1. If the mother is non-Ghanaian, her national-ID fields also become required.
Same pattern as mother, keyed on doubtful_paternity and the father's nationality.
These are taken from your token or assigned automatically; sending them has no effect:
\ncreated_bythird_party_user_idregistry_id (auto-assigned round-robin among active registries in the submitted district)document_number (identifies the record; passed in the URL path, not the body)Fields marked coded accept only values that exist in the system's reference tables and are case/spelling sensitive. Fetch the allowed values from the utilities endpoint before submitting (by utility_type): REGION, DISTRICT, TOWN, GENDER, INFORMANT_TYPE, NATIONAL_ID, PLACE_OF_BIRTH, BIRTH_ATTENDANT, MARITAL_STATUS, EDUCATIONAL_LEVEL, RELIGION, NATIONALITY, BIRTH_TYPE.
region_id / district_id are numeric IDs; the district must belong to the region.\"MALE\", \"MARRIED\".Send to .../registrations/birth/{{documentNumber}}:
{\n \"status\": \"DRAFT\",\n \"region_id\": 1,\n \"district_id\": 1\n}\nEndpoints for submitting, updating and looking up birth records.
\nDRAFT/editable state.process_flow.current_stage and the callback_history for the record.After submission the record moves through review → verification → registration → approval & numbering → certification. Steps 2–6 each fire a callback event (MARKED_COMPLETE, VERIFIED or DUPLICATE_REJECTED, PUSHED_TO_REGISTRATION, COMPLETED, CERTIFIED) to your configured callback_url. See the Callback Events Documentation folder for full details.
GET /integrations/registrations/death/{documentNumber}
Returns the current state and callback history of a death record. Use this to poll a record's progress at any time.
\nThe process_flow.current_stage field returns one of:
SUBMITTED, DRAFT, PENDING_REVIEW, MARKED_COMPLETE, IN_VERIFICATION, VERIFIED, DUPLICATE_REJECTED, IN_REGISTRATION, APPROVED, CERTIFIED
\n\n\n
APPROVEDappears here as a polling stage only — it is never delivered as a webhook. Use theCOMPLETEDcallback to be notified of this stage.
process_flow.stages.certification.is_certified is false while the record is approved but not yet certified, and becomes true once the certificate has been issued.
The callback_history array lists every callback event that has been dispatched for the record, each with its event_type, callback_status and timestamp.
POST https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/registrations/death
Creates a new death registration record for third-party integrations. Authenticate with your API-consumer Token header (Bearer).
\nstatus = DRAFT — saved as-is (return status PENDING); only region_id, district_id and deceased_date_of_death are enforced. Editable later via the update endpoint.status = COMPLETE — at submit time only region_id, district_id and deceased_date_of_death are strictly enforced. The remaining Required fields below are enforced when the record moves through registry review/verification, so a COMPLETE record missing them is accepted at submit but rejected later. Treat the Required list as needed to actually pass.deceased_date_of_death (≤14 days → Early Death; >14 days → Late Death). service_type is recomputed by the server and is safe to omit.Field status below matches the third-party field reference exactly (COMPLETE, to pass review).
\nAll examiner fields are optional.
\nAll mother_* and father_* fields are Optional unless the deceased is a minor (age under the system's minor threshold). In that case mother_first_name/mother_last_name and father_first_name/father_last_name become Conditional (required), and if a parent is non-Ghanaian their national-ID fields are required too.
These are taken from your token or assigned automatically; sending them has no effect:
\ncreated_bythird_party_user_idregistry_id (auto-assigned round-robin among active registries in the submitted district)document_number (generated on create; passed back in the URL to update)Fields marked coded accept only values that exist in the system's reference tables and are case/spelling sensitive. Fetch the allowed values from the utilities endpoint before submitting (by utility_type): REGION, DISTRICT, TOWN, GENDER, INFORMANT_TYPE, NATIONAL_ID, MARITAL_STATUS, EDUCATIONAL_LEVEL, NATIONALITY, and age unit.
region_id / district_id are numeric IDs; the district must belong to the region.\"MALE\", \"SINGLE\".{\n \"status\": \"DRAFT\",\n \"region_id\": 1,\n \"district_id\": 1,\n \"deceased_date_of_death\": \"2026-04-30\"\n}\nEndpoints for submitting and looking up death records.
\nprocess_flow.current_stage and the callback_history for the record.After submission the record moves through review → verification → registration → approval & numbering → certification. Steps 2–6 each fire a callback event (MARKED_COMPLETE, VERIFIED or DUPLICATE_REJECTED, PUSHED_TO_REGISTRATION, COMPLETED, CERTIFIED) to your configured callback_url. See the Callback Events Documentation folder for full details..
Use the Get Birth Record or Get Death Record endpoint to check the current status and callback history of a record.
\nThese are the only event types delivered to your callback_url:
\n\n⚠️
\nAPPROVEDis not a callback event and is never delivered to yourcallback_url. It appears only as a polling stage (see below). Use theCOMPLETEDcallback to be notified when a record reaches this stage.
COMPLETED = all approvals passed and the registration number / UBNC has been generated. The certificate has not yet been issued.CERTIFIED = the certificate has been formally issued (terminal success).registration_no, ubnc and certificate_number, which always hold the same value.The process_flow object in the response shows:
{\n \"process_flow\": {\n \"current_stage\": \"IN_VERIFICATION\",\n \"stages\": {\n \"integration\": { },\n \"verification\": { },\n \"registration\": { },\n \"certification\": { \"is_certified\": false }\n }\n },\n \"callback_history\": [\n {\n \"event_type\": \"MARKED_COMPLETE\",\n \"callback_status\": \"SUCCESS\",\n \"timestamp\": \"2026-01-27T16:48:43+00:00\"\n }\n ]\n}\nprocess_flow.stages.certification.is_certified is false while the record is approved but not yet certified, and becomes true once the certificate has been issued.
process_flow.current_stage returns one of:
\n\n","urlObject":{"path":["api","v1","UserManagementService","integrations","registrations","birth","{{documentNumber}}"],"host":["https://bdrbeta.npontu.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"12f764cb-b587-4887-bc9c-3b1ad875db7b"},{"name":"MARKED_COMPLETE Event","id":"7f9ee758-e33f-4465-8af0-ca12bf3a3fb7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"document_number\": \"BIRTH-121234-2026-0000003\",\n \"event_type\": \"MARKED_COMPLETE\",\n \"status\": \"IN_VERIFICATION\",\n \"description\": \"Record marked complete by officer and moved to verification\",\n \"record_type\": \"BIRTH\",\n \"timestamp\": \"2026-01-29T14:00:00+00:00\",\n \"service_type\": \"EARLY_BIRTH\",\n \"data\": {\n \"child_first_name\": \"JANE\",\n \"child_middle_name\": \"AKOSUA\",\n \"child_last_name\": \"SMITH\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{{your_callback_url}}","description":"\n
APPROVEDappears here as a polling stage only — it is never delivered as a webhook. Use theCOMPLETEDcallback to be notified of this stage.
Triggered when: A registry officer marks the record as complete after reviewing all fields.
\nWhat happens next: Record moves to the verification table for duplicate checking.
\nReturn HTTP 200 with any body (body is ignored).
\n","urlObject":{"host":["{{your_callback_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"7f9ee758-e33f-4465-8af0-ca12bf3a3fb7"},{"name":"DUPLICATE_REJECTED Event","id":"1e2e4075-a27a-44db-a080-e0563e57f341","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"document_number\": \"BIRTH-121234-2026-0000003\",\n \"event_type\": \"DUPLICATE_REJECTED\",\n \"status\": \"REJECTED\",\n \"description\": \"Record rejected as duplicate\",\n \"record_type\": \"BIRTH\",\n \"timestamp\": \"2026-01-29T14:00:00+00:00\",\n \"duplicate_message\": \"Duplicate found - matches existing record BIRTH-121234-2026-0000001\",\n \"data\": {\n \"child_first_name\": \"JANE\",\n \"child_middle_name\": \"AKOSUA\",\n \"child_last_name\": \"SMITH\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"{{your_callback_url}}","description":"Triggered when: The system detects the record is a duplicate during verification.
\nWhat happens next: Record is marked as rejected. No further processing occurs.
\nYou may need to:
\nTriggered when: The record passes duplicate verification checks.
\nWhat happens next: Record is queued to be pushed to the main registration table.
\nTriggered when: The verified record is moved to the main registration table (EarlyBirthRegistration, LateBirthRegistration, EarlyDeathRegistration, or LateDeathRegistration).
\nWhat happens next: Record enters the standard registration workflow with approval levels.
\nTriggered when: The birth record passes all approval levels and the registration number / UBNC is generated.
\nImportant: COMPLETED does not mean a certificate has been issued. At this point the certification record exists but is still pending. The terminal \"certificate issued\" signal is the separate CERTIFIED event — integrators expecting a final certificate signal must listen for CERTIFIED, not COMPLETED.
\n\nThe
\nAPPROVEDstatus you may see on the status lookup endpoint corresponds to this stage.APPROVEDis a polling stage only and is never delivered as a callback — thisCOMPLETEDevent is how you are notified of it.
Return any 2xx status to acknowledge. Failed deliveries retry with exponential backoff (1, 5, 15, 30, 60 min).
Triggered when: The death record passes all approval levels and the registration number / UBNC is generated.
\nImportant: COMPLETED does not mean a certificate has been issued. At this point the certification record exists but is still pending. The terminal \"certificate issued\" signal is the separate CERTIFIED event — integrators expecting a final certificate signal must listen for CERTIFIED, not COMPLETED.
\n\nThe
\nAPPROVEDstatus you may see on the status lookup endpoint corresponds to this stage.APPROVEDis a polling stage only and is never delivered as a callback — thisCOMPLETEDevent is how you are notified of it.
Return any 2xx status to acknowledge. Failed deliveries retry with exponential backoff (1, 5, 15, 30, 60 min).
Triggered when: The certifying officer formally issues the certificate for the birth record.
\nThis is the final, terminal event in the registration workflow. Integrators expecting a \"certificate issued\" signal must listen for this event — not COMPLETED.
\n\n\n
COMPLETEDvsCERTIFIED:COMPLETEDfires earlier, when all approvals pass and the registration number / UBNC is generated (certificate still pending).CERTIFIEDfires here, once the certificate is actually issued. At this pointprocess_flow.stages.certification.is_certifiedbecomestrue.
Return any 2xx status to acknowledge. Failed deliveries retry with exponential backoff (1, 5, 15, 30, 60 min).
Triggered when: The certifying officer formally issues the certificate for the death record.
\nThis is the final, terminal event in the registration workflow. Integrators expecting a \"certificate issued\" signal must listen for this event — not COMPLETED.
\n\n\n
COMPLETEDvsCERTIFIED:COMPLETEDfires earlier, when all approvals pass and the registration number / UBNC is generated (certificate still pending).CERTIFIEDfires here, once the certificate is actually issued. At this pointprocess_flow.stages.certification.is_certifiedbecomestrue.
Return any 2xx status to acknowledge. Failed deliveries retry with exponential backoff (1, 5, 15, 30, 60 min).
This folder documents the real-time callback events the HBDRP platform sends to your configured callback_url as a birth or death record moves through its lifecycle. Each request in this folder is a documentation stub whose body shows a representative payload for that event.
There are exactly six callback events, in flow order:
\n\n\n\n
APPROVEDis not a callback event and is never delivered to yourcallback_url. It exists only as a polling stage on the status lookup endpoint. Listen for theCOMPLETEDcallback instead.
COMPLETED = all approvals passed and the registration number / UBNC has been generated. The certificate has not yet been issued; the certification record is still pending.CERTIFIED = the certificate has been formally issued. This is the terminal \"certificate issued\" signal integrators should wait for.registration_no, ubnc and certificate_number, which always hold the same value.POSTed to your configured callback_url.Content-Type, Accept, X-Event-Type, X-Document-Number, X-Timestamp.POST https://bdrbeta.npontu.com/api/v1/UserManagementService/integrations/utility
Fetches the allowed coded (lookup) values used across birth and death registration payloads (regions, districts, registries, gender, marital status, etc.). Any field marked coded in the registration docs must exactly match a value returned here (case/spelling sensitive). Authenticate with your API-consumer Token header.
\nutility_type valuesCOUNTRY, REGION, NATIONALITY, DISTRICT, REGISTRY, NATIONAL_ID, TOWN, GENDER, BIRTH_TYPE, BIRTH_ATTENDANT, RELIGION, EDUCATIONAL_LEVEL, INFORMANT_TYPE, MARITAL_STATUS, PLACE_OF_BIRTH.
Location lookups cascade — fetch each level using the ID from the level above:
\nCOUNTRY → gives country_idREGION (needs country_id) → gives region_idDISTRICT (needs region_id) → gives district_idREGISTRY (needs district_id)Use the returned numeric IDs for region_id / district_id in registration payloads, and the returned exact names for coded name fields (e.g. gender \"MALE\", marital status \"MARRIED\").
Saved examples cover REGION, DISTRICT, BIRTH_TYPE, and REGISTRY responses.
{ \"utility_type\": \"REGION\", \"country_id\": 1 }\n