OpenCRVS
v1.5
v1.5
  • 👋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 TLS / SSL & DNS
          • 4.3.2.1 LetsEncrypt https challenge in development environments
          • 4.3.2.2 LetsEncrypt DNS challenge in production
          • 4.3.2.3 Static TLS certificates
        • 4.3.3 Configure inventory files
        • 4.3.4 Create a Github environment
          • 4.3.4.1 Environment secrets and variables explained
          • 4.3.4.2 VPN Recipes
        • 4.3.5 Provisioning servers
          • 4.3.5.1 SSH access
          • 4.3.5.2 Building, pushing & releasing your countryconfig code
          • 4.3.5.3 Ansible tasks when provisioning
        • 4.3.6 Deploy
          • 4.3.6.1 Running a deployment
          • 4.3.6.2 Seeding a server environment
          • 4.3.6.3 Login to an OpenCRVS server
          • 4.3.6.5 Resetting a server environment
        • 4.3.7 Backup & Restore
          • 4.3.7.1 Restoring a backup
          • 4.3.7.2 Off-boarding from OpenCRVS
    • 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.5.1: Release notes
      • v1.5.0: Release notes
      • 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.0: Release notes
      • v1.2.1: Release notes
      • Patch: Elasticsearch 7.10.2
      • v1.2.0: Release notes
      • v.1.1.2: Release notes
      • v.1.1.1: Release notes
      • v1.1.0: Release notes
    • Roadmap
Powered by GitBook
On this page
  • Why use the FHIR Location REST API?
  • Using the FHIR Location REST API
  1. Technology
  2. Interoperability

FHIR Location REST API

Create, read, update or archive administrative areas, civil registration offices or health facilities using FHIR.

PreviousNational ID clientNextOther ways to interoperate

Why use the FHIR Location REST API?

You need access to the FHIR Location API for 3 important reasons...

1. Using the FHIR Location API for clients

This API will help you configure integrating clients to understand the relationship to places referenced by ids in payloads such as "Place of birth", "Place of registration", or "Jurisdiction" such as and clients.

For an client, you must submit the correct FHIR Location id for the health facility that OpenCRVS understands in order to correctly track the place of birth.

For a client, you need the correct FHIR Location id when performing advanced searches depending on your parameters.

All FHIR objects such as Location are and have a unique uuid: property that never changes.

2. Changing administrative areas, civil registration offices or facilities

During the configuration step of OpenCRVS you import all administrative areas, civil registration offices and health facilities in CSV files. But over the years of operation, changes occur to your infrastructure and jurisdictional operations.

Sometimes you may wish to add a new office or health facility.

Sometimes you may wish to change the name of an area or health facility.

Sometimes a location may no longer be in use and you want it to not appear as a valid place of birth or death, or a valid area in an address in new event declaration forms.

Note, in OpenCRVS a FHIR Location cannot be deleted entirely, only archived. This is to protect the integrity of any older event registrations where the historical name of the facility or administrative area must be always remembered. That can only be changed via the procedure.

3. Updating population and crude-birth-rate statistics to power the registration "completion rate" performance

During the configuration step of OpenCRVS you import all administrative areas with that are used to calculate changing over time. This calculation depends upon the yearly population of that area and its associated, and ever changing, "crude birth rate". These values are collected by statistical departments in government. To provide accurate performance analytics, the previous year's statistics should be added via this API on a yearly basis.

Using the FHIR Location REST API

https://gateway.<your-domain>/documentation

Reading FHIR Locations

Send a GET request with Content-Type: application/json headers to:

Get ALL administrative structure locations:

https://gateway.<your-domain>/location

or, get a single location:

https://gateway.<your-domain>/location/{{FHIR Location id}}

Getting all FHIR Locations or getting a single FHIR Location by its id, can be performed by any client, publicly on the internet with no authorization headers necessary. If you wish to whitelist access for whatever reason, you can do so via Traefik in Docker compose files.

By adding the FHIR status=active property, you can filter out any deactivated locations that are no longer in use.

Get ALL administrative areas by FHIR type and status:

location?type=ADMIN_STRUCTURE&_count=0&status=active

Get ALL office locations by FHIR type and status:

location?type=CRVS_OFFICE&_count=0&status=active

Get ALL health facilities by FHIR type and status:

location?type=HEALTH_FACILITY&_count=0&status=active

Get a single location by FHIR identifier:

https://gateway.<your-domain>/location?identifier=ADMIN_STRUCTURE_{{statisticalID}}
https://gateway.<your-domain>/location?identifier=HEALTH_FACILITY_{{statisticalID}}
https://gateway.<your-domain>/location?identifier=CRVS_OFFICE_{{statisticalID}}

statisticalID is the adminPCode or custom id you set when importing administrative areas or facility CSVs respectively. We call that a statisticalID because it is generally used by statistics departments in government as opposed to a FHIR id.

Authorization to create, update and archive a FHIR Location

Only a National System Administrator's JWT token can be used to perform these actions as they are potentially destructive and can affect business operations. An Interoperability client does not have permission.

To retrieve a National System Administrators JWT token, login as the national system administrator. In our example, this is the user j.campbell.

In Chrome, right click anywhere on the page, choose "Inspect", and open "Chrome Developer Tools."

Open the "Application" tab and expand "Local Storage".

The JWT is the value for the key "opencrvs"

Double click inside the value and type Ctrl+A to select all, then Ctrl+C to copy the JWT into your clipboard.

Create a FHIR Location

Send a POST request with Content-Type: application/json , and Authorization: Bearer <National System Administrators JWT> headers to the following endpoint with the JSON payload appropriate to your location type:

Administrative area

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

{
  "statisticalID": "TEST_LOCATION",
  "name": "My name",
  "alias": "My alias", // used for a different character set in localisation e.g. Arabic
  "partOf": "Location/0",
  "code": "ADMIN_STRUCTURE",
  "jurisdictionType": "STATE",
  "statistics": [
    {
      "year": 0,
      "male_population": 0,
      "female_population": 0,
      "population": 0,
      "crude_birth_rate": 0
    }
  ]
}

Civil registration office

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

{
  "statisticalID": "TEST_OFFICE_LOCATION",
  "name": "My office",
  "alias": "My office alias", // used for a different character set in localisation e.g. Arabic
  "partOf": "Location/0",
  "code": "CRVS_OFFICE"
}

Health facility

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

{
  "statisticalID": "TEST_HEALTH_LOCATION",
  "name": "My hospital",
  "alias": "My hospital alias", // used for a different character set in localisation e.g. Arabic
  "partOf": "Location/0",
  "code": "HEALTH_FACILITY"
}

Update or Archive a FHIR Location

Send a PUT request with Content-Type: application/json , and Authorization: Bearer <National System Administrators JWT> headers to the following endpoint with the JSON payload appropriate to your location type:

To archive a location, set the status prop to "inactive"

To reinstate a location, set the status prop to "active"

Administrative area

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

{
  "name": "My new name",
  "alias": "My new alias",
  "status": "active",
  "statistics": 
    {
      "year": 0,
      "male_population": 0,
      "female_population": 0,
      "population": 0,
      "crude_birth_rate": 0
    }
  
}

Civil registration office / Health facility

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

{
  "name": "My new name",
  "alias": "My new alias",
  "status": "active"
}

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

A simple test harness for the FHIR Location API is also available in at the following URL:

You can also use the FHIR API URL parameters to search using or other FHIR properties such as .

FHIR Location
Webhooks
National ID
Event Notification
Record Search
"FHIR Resources"
"id"
correct record
statistics
completeness rates
Postman collections
Postman
Swagger
FHIR identifiers
type