Record Search clients
Perform an advanced search of civil registration records from a trusted, external e-Gov service
The Record Search client can perform an advanced search of civil registration records. Use this to help support social protection systems, check the existence of civil registration records or check citizen demographics.
To stop abuse of such a powerful API, all results returned are audited as having been downloaded by the client. System Administrators should be careful to ensure that citizen data is not exposed to untrustworthy individuals by using this API.
All client behaviour is audited and is ultimately the personal responsibility of the National System Administrator of OpenCRVS that created the client. Protect citizen data and do not expose it unnecessarily as you may be in breach of local laws.
Submitting a Record Search
To submit an Record Search, your client must first request an authorization token using your client_id and client_secret.
Record Search Requests
With the token as an authorization header, the following example request will submit a record search in GraphQL. GraphQL is the chosen protocol as this API re-uses the same Advanced Search GraphQL queries that are used buy the OpenCRVS GUI.
The API and parameters explained below. A full list of available Advanced Search GraphQL variables is also explained below.
Search for records using advanced search parameters. This endpoint allows for complex queries based on various attributes of the records.
The name of the GraphQL operation to execute
The GraphQL query string to execute
query searchEvents($advancedSearchParameters: AdvancedSearchParameters!, $sort: String, $count: Int!, $skip: Int!) { searchEvents(sort: $sort, count: $count, skip: $skip, advancedSearchParameters: $advancedSearchParameters) { totalItems results{ id type registration status contactNumber trackingId registrationNumber registeredLocationId duplicates assignment { practitionerId firstName lastName officeName __typename } createdAt modifiedAt __typename } operationHistories { operationType operatedOn operatorRole operatorName { firstNames familyName use __typename } operatorOfficeName operatorOfficeAlias notificationFacilityName notificationFacilityAlias rejectReason rejectComment __typename } __typename } __typename }POST /graphql HTTP/1.1
Host: localhost:7070
Content-Type: application/json
Accept: */*
Content-Length: 2920
{
"operationName": "text",
"query": "query searchEvents($advancedSearchParameters: AdvancedSearchParameters!, $sort: String, $count: Int!, $skip: Int!) {\n searchEvents(sort: $sort, count: $count, skip: $skip, advancedSearchParameters: $advancedSearchParameters) {\n totalItems\n results{\n id\n type\n registration\n status\n contactNumber\n trackingId\n registrationNumber\n registeredLocationId\n duplicates\n assignment {\n practitionerId\n firstName\n lastName\n officeName\n __typename\n }\n createdAt\n modifiedAt\n __typename\n }\n operationHistories {\n operationType\n operatedOn\n operatorRole\n operatorName {\n firstNames\n familyName\n use\n __typename\n }\n operatorOfficeName\n operatorOfficeAlias\n notificationFacilityName\n notificationFacilityAlias\n rejectReason\n rejectComment\n __typename\n \n }\n __typename\n }\n __typename\n}",
"variables": {
"sort": "text",
"count": 1,
"skip": 1,
"advancedSearchParameters": {
"brideDoB": "text",
"brideDoBEnd": "text",
"brideDoBStart": "text",
"brideFamilyName": "text",
"brideFirstNames": "text",
"brideIdentifier": "text",
"childDoB": "text",
"childDoBEnd": "text",
"childDoBStart": "text",
"childFirstNames": "text",
"childGender": "text",
"childIdentifier": "text",
"childLastName": "text",
"compositionType": [
"text"
],
"contactEmail": "text",
"contactNumber": "text",
"dateOfEvent": "text",
"dateOfEventEnd": "text",
"dateOfEventStart": "text",
"dateOfMarriage": "text",
"dateOfRegistration": "text",
"dateOfRegistrationEnd": "text",
"dateOfRegistrationStart": "text",
"deceasedDoB": "text",
"deceasedDoBEnd": "text",
"deceasedDoBStart": "text",
"deceasedFamilyName": "text",
"deceasedFirstNames": "text",
"deceasedGender": "text",
"deceasedIdentifier": "text",
"declarationJurisdictionId": "text",
"declarationLocationId": "text",
"event": "birth",
"eventCountry": "text",
"eventLocationId": "text",
"eventLocationLevel1": "text",
"eventLocationLevel2": "text",
"eventLocationLevel3": "text",
"eventLocationLevel4": "text",
"eventLocationLevel5": "text",
"eventLocationLevel6": "text",
"fatherDoB": "text",
"fatherDoBEnd": "text",
"fatherDoBStart": "text",
"fatherFamilyName": "text",
"fatherFirstNames": "text",
"fatherIdentifier": "text",
"groomDoB": "text",
"groomDoBEnd": "text",
"groomDoBStart": "text",
"groomFamilyName": "text",
"groomFirstNames": "text",
"groomIdentifier": "text",
"informantDoB": "text",
"informantDoBEnd": "text",
"informantDoBStart": "text",
"informantFamilyName": "text",
"informantFirstNames": "text",
"informantIdentifier": "text",
"motherDoB": "text",
"motherDoBEnd": "text",
"motherDoBStart": "text",
"motherFamilyName": "text",
"motherFirstNames": "text",
"motherIdentifier": "text",
"name": "text",
"nationalId": "text",
"recordId": "text",
"registrationNumber": "text",
"registrationStatuses": [
"text"
],
"timePeriodFrom": "text",
"trackingId": "text"
}
}
}OK
{
"searchEvents": {
"__typename": "text",
"id": "text",
"operationHistories": [
{
"__typename": "text",
"notificationFacilityAlias": [
"text"
],
"notificationFacilityName": "text",
"operatedOn": "2017-01-01",
"operationType": "text",
"operatorName": [
{
"__typename": "text",
"familyName": "text",
"firstNames": "text",
"use": "text"
}
],
"operatorOfficeAlias": [
"text"
],
"operatorOfficeName": "text",
"operatorRole": "text",
"rejectComment": "text",
"rejectReason": "text"
}
],
"registration": {
"__typename": "text",
"assignment": {
"__typename": "text",
"firstName": "text",
"lastName": "text",
"officeName": "text",
"practitionerId": "text"
},
"contactNumber": "text",
"createdAt": "text",
"duplicates": [
"text"
],
"modifiedAt": "text",
"registeredLocationId": "text",
"registrationNumber": "text",
"status": "text",
"trackingId": "text"
},
"results": [
{}
],
"totalItems": 1,
"type": "text"
}
}GraphQL Parameters
operationName
Must be "searchEvents"
query
Use the exhaustive GraphQL syntax supplied or remove individual return parameters if you do not require that citizen information. Protect citizen's privacy! Only request what you need.
variables.advancedSearchParameters
A JSON object of optional search parameters listed below
count
The number of records to be returned per page
skip
Pagination offset
GraphQL variables.advancedSearchParameters object
We recommend that you use the Advanced Search feature in the OpenCRVS application and monitor the GraphQL payload that is sent to the Gateway using the Chrome Developer Tools "Network" tab, in order to understand how these parameters are formatted. The table below lists all possible parameters with a description and example where we feel further explanation is helpful.
event
An enum for the registration event. Can be "birth" or "death"
birth
name
A string that can be used to search ALL names.
registrationStatuses
An array of possible application status enums. Possible statuses are listed here. Remove "_STATUS" when providing the value. Examples listed in the next cell.
["REGISTERED", "CERTIFIED", "ISSUED"]
dateOfEvent
The date of event. YYYY-MM-DD
2022-12-31recordId
A unique uuid for the registration that forms part of the QR code URL on the certificate. Use this to validate a certificate.
dateOfEventStart
If you dont know the date of event, you can enter a start and end date to search within a range. YYYY-MM-DD
dateOfEventEnd
As above
contactNumber
The informant's mobile phone number with country code
nationalId
Any national id associated with any individual who has been involved in a registration event as a string
registrationNumber
An event registration number as a string
trackingId
An application tracking id as a string
dateOfRegistration
The date of registration. YYYY-MM-DD
dateOfRegistrationStart
If you dont know the date of registration, you can enter a start and end date to search within a range. YYYY-MM-DD
dateOfRegistrationEnd
As above
declarationLocationId
A FHIR Location uuid for the a registration office. You can search all registrations that were made in an office. You retrieve these ids using our open Location API. Your offices are customised for your country needs in this step.
031dc5a6-ea63-47e6-a818-191cc12a9b92
eventLocationId
When searching by the hospital location in which an event took place, this is a FHIR Location uuid for a facility that is already in the OpenCRVS database to track places of births or deaths in health institutions. You can retrieve these ids using our open Location API. Your health facilities are customised for your country needs in this step.
031dc5a6-ea63-47e6-a818-191cc12a9b92
eventCountry
When searching for the administrative location in which an event took place e.g. place of birth, then this is an alpha 3 country code for the country.
eventLocationLevel1
When searching for the administrative location in which an event took place e.g. place of birth, then this is a FHIR Location uuid for the locationLevel1 if applicable, technically expressed in FHIR as a "state". You can retrieve these ids using our open Location API. Your location levels are customised for your country needs in this step.
031dc5a6-ea63-47e6-a818-191cc12a9b92
eventLocationLevel2
When searching for the administrative location in which an event took place e.g. place of birth, then this is a FHIR Location uuid for the locationLevel2 if applicable, technically expressed in FHIR as a "district". You can retrieve these ids using our open Location API. Your location levels are customised for your country needs in this step.
031dc5a6-ea63-47e6-a818-191cc12a9b92
eventLocationLevel3
As above
eventLocationLevel4
As above
eventLocationLevel5
As above
childFirstNames
As above
childLastName
As above
childDoB
As above
childDoBStart
As above
childDoBEnd
As above
childGender
A string. Can be "male", "female" or "unknown"
childIdentifier
A string used to search by National ID
deceasedFirstNames
As above
deceasedFamilyName
As above
deceasedGender
A string. Can be "male", "female" or "unknown"
deceasedDoB
As above
deceasedDoBStart
As above
deceasedDoBEnd
As above
deceasedIdentifier
A string used to search by National ID
motherFirstNames
As above
motherFamilyName
As above
motherDoB
As above
motherDoBStart
As above
motherDoBEnd
As above
motherIdentifier
As above
fatherFirstNames
As above
fatherFamilyName
As above
fatherDoB
As above
fatherDoBStart
As above
fatherDoBEnd
As above
fatherIdentifier
As above
informantFirstNames
As above
informantFamilyName
As above
informantDoB
As above
informantDoBStart
As above
informantDoBEnd
As above
informantIdentifier
As above
groomDoB
As above
groomDoBStart
As above
groomDoBEnd
As above
groomIdentifier
As above
groomFirstNames
As above
groomFamilyName
As above
brideDoB
As above
brideDoBStart
As above
brideDoBEnd
As above
brideIdentifier
As above
brideFirstNames
As above
brideFamilyName
As above
Record Search Response
The response from a record search is not FHIR, but an Elasticsearch response.
After a search has completed and if you search for any record returned, you will see that in Record Audit, an entry shows that this client has accessed the personally identifiable citizen data on the record.
Last updated