APIs for system administrators

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

FHIR Location REST API

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

1. In order to get FHIR IDs for locations required in Event Notification or deciphering location information from FHIR IDs returned from a Record Search or Webhook response

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

For an Event Notification 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 Record Search client, you need the correct FHIR Location id when performing advanced searches depending on your parameters.

All FHIR objects such as Location are "FHIR Resources" and have a unique uuid: "id" 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.

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 statistics that are used to calculate changing completeness rates 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

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

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

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

Get all locations

get
Query parameters
typestring · enumOptionalPossible values:
identifierstringOptional

The unique identifier for a location

Pattern: ^[a-zA-Z0-9_]+$
namestringOptionalPattern: ^[a-zA-Z0-9_,.\s]+$
statusstring · enumOptionalPossible values:
_countnumberOptional

Number of locations to return per page, Use 0 to return all locations

Responses
200
OK
application/json
get
GET /locations HTTP/1.1
Host: localhost:7070
Accept: */*
200

OK

{
  "resourceType": "Bundle",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "meta": {
    "lastUpdated": "2025-07-18T22:30:09.143Z"
  },
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "text",
      "url": "text"
    }
  ],
  "entry": [
    {
      "fullUrl": "text",
      "resource": {
        "resourceType": "Location",
        "identifier": [
          {
            "system": "text",
            "value": "text"
          }
        ],
        "name": "text",
        "alias": [
          "text"
        ],
        "status": "text",
        "mode": "text",
        "partOf": {
          "reference": "text"
        },
        "type": {
          "coding": [
            {
              "system": "text",
              "code": "text"
            }
          ]
        },
        "physicalType": {
          "coding": [
            {
              "code": "text",
              "display": "text"
            }
          ]
        },
        "meta": {
          "lastUpdated": "2025-07-18T22:30:09.143Z",
          "versionId": "text"
        },
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  ]
}

Get a single location

get
Path parameters
locationIdstringRequired
Responses
200
OK
application/json
get
GET /locations/{locationId} HTTP/1.1
Host: localhost:7070
Accept: */*
200

OK

{
  "resourceType": "Bundle",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "meta": {
    "lastUpdated": "2025-07-18T22:30:09.143Z"
  },
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "https://example.com"
    }
  ],
  "entry": [
    {
      "fullUrl": "text",
      "resource": {
        "resourceType": "Location",
        "identifier": [
          {
            "system": "text",
            "value": "text"
          }
        ],
        "name": "text",
        "alias": [
          "text"
        ],
        "status": "text",
        "mode": "text",
        "partOf": {
          "reference": "text"
        },
        "type": {
          "coding": [
            {
              "system": "text",
              "code": "text"
            }
          ]
        },
        "physicalType": {
          "coding": [
            {
              "code": "text",
              "display": "text"
            }
          ]
        },
        "meta": {
          "lastUpdated": "2025-07-18T22:30:09.143Z",
          "versionId": "text"
        },
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  ]
}

When creating a new location, 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.

Create a location

post
Body
any ofOptional
or
Responses
200
OK
post
POST /locations HTTP/1.1
Host: localhost:7070
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "statisticalID": "text",
  "name": "text",
  "alias": "text",
  "partOf": "text",
  "code": "ADMIN_STRUCTURE",
  "jurisdictionType": "DISTRICT",
  "statistics": [
    {
      "year": 1,
      "male_population": 1,
      "female_population": 1,
      "population": 1,
      "crude_birth_rate": 1
    }
  ]
}
200

OK

No content

Update a location

put
Path parameters
locationIdstringRequired
Body
namestringOptional
aliasstringOptional

Optional secondary name for the location

statusstring · enumOptionalPossible values:
Responses
200
OK
put
PUT /locations/{locationId} HTTP/1.1
Host: localhost:7070
Content-Type: application/json
Accept: */*
Content-Length: 150

{
  "name": "text",
  "alias": "text",
  "status": "active",
  "statistics": {
    "year": 1,
    "male_population": 1,
    "female_population": 1,
    "population": 1,
    "crude_birth_rate": 1
  }
}
200

OK

No content

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

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

Authorization to create, update and archive a FHIR Location

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.

Update or Archive a FHIR Location

Last updated