Maternity Record API

A maternity record is a structured and versioned json-document, consisting of a root "record" object, with sub-objects underneath containing clinically relevant data for giving pregnancy care. These are all documented in the resources file.

Any changes to the main record-object or the sub-objects are stored as separate "events", essentially creating a new version of the object each time an update happens. This makes it possible to keep track of all changes, when they happened, and who made them, creating a versioned history of the document(s).

This is stored as metadata on each of the objects, as described in the metadata doc. The metadata-doc also describes how versioning works.

Endpoints

Available API-endpoints are listed below

(They start with /apiurl/record, i.e https://test.maternity-record.hit.nhn.no/api/maternity-record/v1/record/)

URL Method Description
/status GET Get maternity record status for patient (see status-doc)
/record POST Create a maternity record for a patient
/record/record_id GET Get the maternity record with the given ID for a patient
/record/record_id/RESOURCE_TYPE POST Create resource for maternity record with given id
/record/record_id/RESOURCE_TYPE PUT Update resource for maternity record with given id

Valid RESOURCE_TYPE are listed in Resources.

Authorization

The call the maternity-record API, a HelseID user token is required. See the authorizations-docs for details here

Status

Before creating a maternity record for a patient, we recommend calling the status-endpoint to see if one already exists. Once an active maternity record exists for a patient, another one cannot be created (max one active record at the time per patient). For more details see Status endpoint

Creating a new maternity record for a patient

To start, a patient needs an active maternity record before additional info and sub-resources can be added. Just as you in the past needed a physical maternity record to fill in the data, you need an active maternity record on the patient digitally as well.

Create Maternity Record

POST to /apiurl/record, i.e https://test.maternity-record.hit.nhn.no/api/maternity-record/v1/record/

curl --location --request POST 'https://test.maternity-record.hit.nhn.no/api/maternity-record/v1/record/' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiI......<HelseId token>' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Accept: application/json' \
--header 'hit-user-role: %7B%0A++++%22system%22%3A+%22urn%3Aoid%3A2.16.578.1.12.4.1.1.9060%22%2C%0A++++%22code%22%3A+%22LE%22%0A%7D' \
--header 'hit-access-basis: SAMTYKKE' \
--header 'hit-source-system: My EPJ system name' \
--header 'hit-patient-pid: XXXXXXXXXX'

Response:

{
  "metadata": {
    "recordId": "37331627-4e2a-4454-b3ec-ddc742e724c1",
    "status": "ACTIVE",
    "version": 1,
    "lastUpdated": "2024-10-29T11:45:06.866",
    "lastUpdatedBy": {
      "userType": "HEALTH_CARE_PROFESSIONAL",
      "orgNr": "998570328",
      "orgNrDisplay": "Munkholmen Legesenter",
      "hprNr": "222200063",
      "hprRole": "LE",
      "name": "Lillehagen, Rolf Fos"
    }
  },
  "mother": null,
  "currentPregnancy": null,
  "geneticDisorders": null,
  "lifestyleFactors": null,
  ...
}

Once this is done, sub-resources can be added that make up the maternity record, such as mother, lifestyle factors and so on. For a detailed description of each of the resources available, see Resources.

Note that most requests require a record_id to be sent in the url. This is the id of the "root" maternity record, and can be fetched using the status-endpoint ( Status endpoint), and is also returned when creating a new maternity record, in the metadata (metadata.recordId).

GET /record/record_id

Returns the maternity record with the given ID for the patient.

Response:

{
  "metadata": {
    "recordId": "37331627-4e2a-4454-b3ec-ddc742e724c1",
    "status": "ACTIVE",
    "version": 1,
    "lastUpdated": "2024-10-29T11:45:06.866",
    "lastUpdatedBy": {
      "userType": "HEALTH_CARE_PROFESSIONAL",
      "orgNr": "998570328",
      "orgNrDisplay": "Munkholmen Legesenter",
      "hprNr": "222200063",
      "hprRole": "LE",
      "name": "Lillehagen, Rolf Fos"
    }
  },
  "mother": {
    ...
  },
  "currentPregnancy": {
    ...
  },
  "geneticDisorders": {
    ...
  },
  "lifestyleFactors": {
    ...
  },
  "medicalConditions": null,
  "medication": null,
  "clinicalTests": null,
  ...
}

Note that any "sub"-objects that haven't been created will be null