Event Notification clients

Submitting full or partial event applications into OpenCRVS from an external service such as a health institution or public portal.

An Event Notification client can submit full or partial events to an OpenCRVS office. You can find the technical documentation for the Event Notification APIs in our Swagger documentation.

You can use our Postman collections to test the Event Notification API functionality. Specifically, use the Event Notification - v1.9.0 collection. Postman is a tool you can download to test API access before building your integrations.

The following images and examples use the fictional country Farajaland and its birth registration configuration. Your actual events and workflows may vary depending on your country’s configuration.

An Event Notification in the Farajaland 'In Progress' view

When Event Notifications are received in OpenCRVS, they are audited and logged as being received from an automated client. Events submitted via the Event Notification API are saved with the status NOTIFIED.

Record audit view for an Event Notification

Submitting an Event Notification

To submit an Event Notification, your client must first request an authorization token using your client_id and client_secret.

Event Notification Requests

Using the token in the Authorization header, an event is notified via two sequential API requests:

1. POST /api/events/events to initialize the event

2. POST /api/events/events/notifications to submit full or partial event data and trigger the notification

The example below demonstrates how to submit a simple birth declaration based on the Farajaland configuration. This example will contain the child's name and date of birth details.

POST /api/events/events
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "type": "v2.birth",
  "transactionId": "{{uuid}}",
  "dateOfEvent": {
    "fieldId": "child.dob"
  }
}

This request will return a response containing the event ID in the id field. You must use this eventId in the subsequent request.

Once the event is initialized, you can submit the notification:

POST /api/events/events/notifications
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "eventId": "{{eventId}}",
  "transactionId": "{{uuid}}",
  "declaration": {
    "child.firstname": "Jane",
    "child.surname": "Doe",
    "child.dob": "{{yyyy-MM-dd}}"
  },
  "annotation": {},
  "createdAtLocation": "{{officeId}}", // Retrievable from the location API - See "APIs for system administrators"
  "type": "NOTIFY"
}

For full API details, refer to the Swagger documentation.