OpenCRVS
v1.4
v1.4
  • 👋Welcome!
  • CRVS Systems
    • Understanding CRVS
    • Effective digital CRVS systems
    • OpenCRVS within a government systems architecture
    • OpenCRVS Value Proposition
  • Product Specifications
    • Functional Architecture
    • Workflow management
    • Status Flow Diagram
    • Users
      • Examples
    • Core functions
      • 1. Notify event
      • 2. Declare event
      • 3. Validate event
      • 4. Register event
      • 5. Print certificate
      • 6. Issue certificate
      • 7. Search for a record
      • 8. View record
      • 9. Correct record
      • 10. Verify record
      • 11. Archive record
      • 12. Vital statistics export
    • Support functions
      • 13. Login
      • 14. Audit
      • 15. Deduplication
      • 16. Performance management
      • 17. Payment
      • 18. Learning
      • 19. User support
      • 20. User onboarding
    • Admin functions
      • 21. User management
      • 22. Comms management
      • 23. Content management
      • 24. Config management
    • Data functions
      • 25. Legacy data import
      • 26. Legacy paper import
  • Technology
    • Architecture
      • Performance tests
    • Standards
      • FHIR Documents
        • Event Composition
        • Person
        • Registration Task
        • Event Observations
        • Locations
    • Security
    • Interoperability
      • Create a client
      • Authenticate a client
      • Event Notification clients
      • Record Search clients
      • Webhook clients
      • National ID client
      • FHIR Location REST API
      • Other ways to interoperate
  • Default configuration
    • Intro to Farajaland
    • Civil registration in Farajaland
    • OpenCRVS configuration in Farajaland
      • Application settings
      • User / role mapping
      • Declaration forms
      • Certificate templates
    • Business process flows in Farajaland
  • Setup
    • 1. Planning an OpenCRVS Implementation
    • 2. Establish project and team
    • 3. Gather requirements
      • 3.1 Mapping business processes
      • 3.2 Mapping offices and user types
      • 3.3 Define your application settings
      • 3.4 Designing event declaration forms
      • 3.5 Designing a certificate template
    • 4. Installation
      • 4.1 Set-up a local development environment
        • 4.1.1 Install the required dependencies
        • 4.1.2 Install OpenCRVS locally
        • 4.1.3 Starting and stopping OpenCRVS
        • 4.1.4 Log in to OpenCRVS locally
        • 4.1.5 Tooling
          • 4.1.5.1 WSL support
      • 4.2 Set-up your own, local, country configuration
        • 4.2.1 Fork your own country configuration repository
        • 4.2.2 Set up administrative address divisions
          • 4.2.2.1 Prepare source file for administrative structure
          • 4.2.2.2 Prepare source file for statistics
        • 4.2.3 Set up CR offices and Health facilities
          • 4.2.3.1 Prepare source file for CRVS Office facilities
          • 4.2.3.2 Prepare source file for health facilities
        • 4.2.4 Set up employees & roles for testing or production
          • 4.2.3.1 Prepare source file for employees
          • 4.2.3.2 Configure role titles
        • 4.2.5 Set up application settings
          • 4.2.5.1 Managing language content
            • 4.2.5.1.1 Informant and staff notifications
          • 4.2.5.2 Configuring Metabase Dashboards
        • 4.2.6 Configure certificate templates
        • 4.2.7 Configure declaration forms
          • 4.2.7.1 Configuring an event form
        • 4.2.8 Seeding & clearing your local databases
        • 4.2.9 Countryconfig API endpoints explained
      • 4.3 Set-up a server-hosted environment
        • 4.3.1 Verify servers & create a "provision" user
        • 4.3.2 HTTPS & Networking
        • 4.3.3 Create a Github environment
          • 4.3.3.1 Environment secrets and variables explained
        • 4.3.4 Provision environments
          • 4.3.4.1 Building, pushing & releasing your countryconfig code
        • 4.3.5 Deploy
    • 5. Functional configuration
      • 5.1 Configure application settings
      • 5.2 Configure registration periods and fees
      • 5.3 Managing system users
    • 6. Quality assurance testing
    • 7. Go-live
      • 7.1 Pre-Deployment Checklist
    • 8. Operational Support
    • 9. Monitoring
      • 9.1 Application logs
      • 9.2 Infrastructure health
      • 9.3 Routine monitoring checklist
      • 9.4 Setting up alerts
      • 9.5 Managing a Docker Swarm
  • General
    • Community
    • Contributing
    • Releases
      • v1.4.1: Release notes
      • v1.4.0 to v1.4.1 Migration notes
      • v1.4.0 Release notes
      • v1.3.* to v1.4.* Migration notes
      • v1.3.5: Release notes
      • v1.3.4: Release notes
      • v1.3.3: Release notes
      • v1.3.1: Release notes
      • v1.3.* to v1.3.* Migration notes
      • v1.3.0: Release notes
      • v1.2.* to v1.3.* Migration notes
        • v1.2 to v1.3: Form migration
      • v1.2.1: Release notes
      • Patch: Elasticsearch 7.10.2
      • v1.2.0: Release notes
      • v1.1.* to v1.2.* Migration notes
      • v.1.1.2: Release notes
      • v.1.1.1: Release notes
      • v1.1.0: Release notes
    • Interoperability roadmap
    • Product roadmap
Powered by GitBook
On this page
  1. Technology
  2. Interoperability

Record Search clients

Perform an advanced search of civil registration records from a trusted, external e-Gov service

PreviousEvent Notification clientsNextWebhook clients

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.

A daily limit of 2000 Record Search requests per client, per day is hardcoded into OpenCRVS Core. Any subsequent requests will fail.

Submitting a Record Search

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.

https://gateway.your_domain/graphql

The GraphQL parameters are explained below. A full list of available Advanced Search GraphQL variables is also explained below.

POST https://gateway.<your_domain>/graphql
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "operationName": "searchEvents",
  "query": "query searchEvents($advancedSearchParameters: AdvancedSearchParametersInput!, $sort: String, $count: Int, $skip: Int) {\nsearchEvents(\n  advancedSearchParameters: $advancedSearchParameters\n  sort: $sort\n  count: $count\n  skip: $skip\n) {\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        userId\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    ... on BirthEventSearchSet {\n      dateOfBirth\n      childName {\n        firstNames\n        familyName\n        use\n        __typename\n      }\n      __typename\n    }\n    ... on DeathEventSearchSet {\n      dateOfDeath\n      deceasedName {\n        firstNames\n        familyName\n        use\n        __typename\n      }\n      __typename\n    }\n    __typename\n  }\n  __typename\n}}",  
  "variables": {"advancedSearchParameters": {
      "event": "birth",
      "registrationStatuses": ["REGISTERED"],
      "childGender": "male",
      "dateOfRegistrationEnd": "2022-12-31T23:59:59.999Z",
      "dateOfRegistrationStart": "2021-11-01T00:00:00.000Z",
      "declarationJurisdictionId": "576uyegf7 .... ", // A FHIR Location ID for an admin level
      "eventLocationId": "aaabuifr87h ...", // A FHIR Location ID for a health facility where the birth or death took place
      "fatherFirstNames": "Dad",
      "motherFirstNames": "Mom"
    },
    "count": 10,
    "skip": 0
  }
}

GraphQL Parameters

Parameter
Description

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.

Parameter
Description
Example

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

["IN_PROGRESS", "REGISTERED"]

dateOfEvent

The date of event. YYYY-MM-DD

recordId

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

031dc5a6-ea63-47e6-a818-191cc12a9b92

declarationJurisdictionId

031dc5a6-ea63-47e6-a818-191cc12a9b92

eventLocationId

031dc5a6-ea63-47e6-a818-191cc12a9b92

eventCountry

eventLocationLevel1

031dc5a6-ea63-47e6-a818-191cc12a9b92

eventLocationLevel2

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. The audit experience is explained below the example payload.

{
  "data": {
    "searchEvents": {
      "totalItems": 3,
      "results": [
        {
          "id": "cb813494-9339-48dd-85a1-156278436f30",
          "type": "Birth",
          "registration": {
            "status": "CERTIFIED",
            "contactNumber": "+260760001907",
            "trackingId": "BHKTHM7",
            "registrationNumber": "2023BHKTHM7",
            "registeredLocationId": "712502d2-5ea2-49d9-86df-a7d61f3f351f",
            "duplicates": null,
            "assignment": null,
            "createdAt": "1673047650433",
            "modifiedAt": null,
            "__typename": "RegistrationSearchSet"
          },
          "operationHistories": [ ... ],
          "dateOfBirth": "2022-10-26",
          "childName": [
            {
              "firstNames": "Santiago",
              "familyName": "Schmeler",
              "use": "en",
              "__typename": "HumanName"
            },
            {
              "firstNames": "",
              "familyName": null,
              "use": "fr",
              "__typename": "HumanName"
            }
          ],
          "__typename": "BirthEventSearchSet"
        },
        {
          "id": "b2fd5270-49c1-4227-8625-d874b6eef25d",
          "type": "Birth",
          "registration": {
            "status": "CERTIFIED",
            "contactNumber": "+260754288799",
            "trackingId": "BBPX0DM",
            "registrationNumber": "2023BBPX0DM",
            "registeredLocationId": "712502d2-5ea2-49d9-86df-a7d61f3f351f",
            "duplicates": null,
            "assignment": null,
            "createdAt": "1673048958068",
            "modifiedAt": null,
            "__typename": "RegistrationSearchSet"
          },
          "operationHistories": [ ... ],
          "dateOfBirth": "2022-08-31",
          "childName": [
            {
              "firstNames": "Price",
              "familyName": "Lind",
              "use": "en",
              "__typename": "HumanName"
            },
            {
              "firstNames": "",
              "familyName": null,
              "use": "fr",
              "__typename": "HumanName"
            }
          ],
          "__typename": "BirthEventSearchSet"
        },
        {
          "id": "a7c641cb-9671-4715-a1a4-ecee08def9b0",
          "type": "Birth",
          "registration": {
            "status": "CERTIFIED",
            "contactNumber": "+260751978586",
            "trackingId": "BXZJNML",
            "registrationNumber": "2023BXZJNML",
            "registeredLocationId": "712502d2-5ea2-49d9-86df-a7d61f3f351f",
            "duplicates": null,
            "assignment": null,
            "createdAt": "1673062235276",
            "modifiedAt": null,
            "__typename": "RegistrationSearchSet"
          },
          "operationHistories": [ ... ],
          "dateOfBirth": "2021-12-11",
          "childName": [
            {
              "firstNames": "Nash",
              "familyName": "Cruickshank",
              "use": "en",
              "__typename": "HumanName"
            },
            {
              "firstNames": "",
              "familyName": null,
              "use": "fr",
              "__typename": "HumanName"
            }
          ],
          "__typename": "BirthEventSearchSet"
        }
      ],
      "__typename": "EventSearchResultSet"
    }
  }
}

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.

You can use our to test Record Search API functionality. is a tool you can download to test API access before building your integrations.

To submit an Record Search, your client must first request an using your client_id and client_secret.

You can browse to the using an authorization header to view the full documentation for the searchEvents GraphQL query.

An array of possible application status enums.

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 . Your offices are customised for your country needs in

A FHIR Location uuid for the immediate administrative level parent, such as a district or state, that the office is partOf. You can retrieve these ids using our open . Your offices are customised for your country needs in

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 . Your health facilities are customised for your country needs in

When searching for the administrative location in which an event took place e.g. place of birth, then this is an for the country.

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 . Your location levels are customised for your country needs in .

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 . Your location levels are customised for your country needs in .

2022-12-31
Postman collections
Postman
authorization token
GraphQL Playground
Possible statuses
Location API
this step.
Location API
this step.
Location API
this step.
alpha 3 country code
Location API
this step
Location API
this step
The GraphQL Playground for OpenCRVS