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
/history	GET	Get all maternity record status' for a patient (any current and for previous pregnancies) (See history doc)
/history/record_id	GET	Get all versions/changes of the given maternity record (See history doc)
/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/updateStatus	POST	Update the status/state of a maternity record
/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
/record/record_id/antenatalAppointments/resource_id	PUT	Update an antenatal appointment
/record/record_id/antenatalAppointments/resource_id	DELETE	Delete an antenatal appointment
/record/record_id/symphysisFundalHeights/resource_id	PUT	Update a symphysis fundal height measurement
/record/record_id/symphysisFundalHeights/resource_id	DELETE	Delete a symphysis fundal height measurement

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

**In the testing environment, we can provide a temporary access token if you have not yet implemented HelseID or are testing requests using tools like Postman. **

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 which can be created with and without any data.

1. Create Maternity Record with data

Important to note, if any of the resources/data fail validation or is not properly processed in the API, a maternity record is not created. In other words, either every resource and maternity record is created or nothing at all. All resources can be created with the maternity record, except symphysisFundalHeights and antenatalAppointments

This is a sample request on how to create maternity record with data:

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 'nhn-source-system: My EPJ system name' \
--header 'nhn-patient-nin: XXXXXXXXXX' \
--data '
    {
      "mother": {
        "name": "Mamma Ku",
        "address": "Trimveien 8, 0372 OSLO"
      },
    
      "clinicalTests": {
        "hemoglobin": 20.0,
        "ferritin": 20.29,
      },
      "rhesusDNegative": null,
      "vitalMeasurementsBeforePregnancy": {
        "height": 280.0,
        "prePregnancyWeight": 90.0,
        "bMI": null
      }
    }
'

2. Create empty Maternity Record

POST to /apiurl/record, i.e https://test.maternity-record.hit.nhn.no/api/maternity-record/v1/record/ without any data in the request body

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 'nhn-source-system: My EPJ system name' \
--header 'nhn-patient-nin: XXXXXXXXXX'

Response:

{
  "metadata": {
    "recordId": "37331627-4e2a-4454-b3ec-ddc742e724c1",
    "recordStatus": {
      "status": "ACTIVE"
    },
    "version": 1,
    "recordLastUpdated" : "2025-04-04T14:44:55Z",
    "lastUpdated": "2025-04-04T14:44:55Z",
    "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).

Reading a maternity record

GET /record/record_id

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

Response:

{
  "metadata": {
    "recordId": "37331627-4e2a-4454-b3ec-ddc742e724c1",
    "recordStatus": {
      "status": "ACTIVE"
    },
    "version": 1,
    "recordLastUpdated" : "2025-04-04T14:38:49Z",
    "lastUpdated": "2025-03-05T06:41:27.217541Z",
    "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

Ending a maternity record

To end a maternity record, either because the baby is delivered, or for another reason, the POST /record/record_id/updateStatus endpoint can be used. This will update the "metadata" of the root maternity record object. Note that this metadata object is slightly different from the metadata-object of the other sub-resources, having a recordId and a recordStatus field.

For a overview of the datastructure see metadata

{
  "metadata": {
    "recordId": "37331627-4e2a-4454-b3ec-ddc742e724c1",
    "recordStatus": {
      "status": "ACTIVE"
    },
    "version": 1,
    "recordLastUpdated" : "2025-04-04T14:38:49Z",
    "lastUpdated": "2025-04-04T14:38:49Z",
    "lastUpdatedBy": {
      ...
    }
  },
  ...
}

The recordStatus-object contains whether the maternity record is "active"/currently in use. The valid statuses are:

Active

The maternity record is currently in use

{
  "recordStatus": {
    "status": "ACTIVE"
  }
}

Delivered

The maternity record is finished, and the baby has been born. Including a DateTime of when the delivery happened, and a true/false value stating if the baby was alive, or it was a still birth.

{
  "recordStatus": {
    "status": "DELIVERED",
    "deliveryDate": "2025-03-05T06:41:27.217541Z",
    "liveBirth": true
  }
}

Teminated

The maternity record is no longer in use, because the pregnancy was terminated before term. Should primarily be used if the pregnancy ends before week X.

{
  "recordStatus": {
    "status": "TERMINATED",
    "terminationDate": "2025-03-05T06:41:27.217541Z"
  }
}

Entered in error

The maternity record was created by mistake, and has been removed. A new maternity record should be created if needed if a record has this status.

{
  "recordStatus": {
    "status": "ENTERED_IN_ERROR"
  }
}

To update the status using the updateStatus-endpoint, the body should contain the recordStatus-object, and the current version of the maternity record, e.g.:

POST /record/record_id/updateStatus

{
  "version": 1,
  "recordStatus": {
    "status": "DELIVERED",
    "deliveryDate": "2025-03-05T06:41:27.217541Z",
    "liveBirth": true
  }
}

Removing/deleting data from a maternity record

Because a maternity record is a versioned object with versioned sub-objects, we do not allow "deleting" sub-objects with a regular delete-request. Instead, to remove data, one should simply update (PUT) new data with empty/null-values.

curl --location --request PUT 'https://test.maternity-record.hit.nhn.no/api/maternity-record/v1/record/record_id/medicalConditions' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiI......<HelseId token>' \
--header 'Content-Type: application/json; charset=UTF-8' \
--header 'Accept: application/json' \
--header 'nhn-source-system: My EPJ system name' \
--header 'nhn-patient-nin: XXXXXXXXXX' \
--data   '{"metadata": {
            "version": 2
            }
          }'

The only exception to this are list elements, like prenatal consultations and symphysis fundal heights, where a regular delete-request can be used to mark a consultation as "entered in error".

curl --location --request DELETE 'https://test.maternity-record.hit.nhn.no/api/maternity-record/v1/record/record_id/antenatalAppointments/resource_id' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiI......<HelseId token>' \
--header 'nhn-source-system: My EPJ system name' \
--header 'nhn-patient-nin: XXXXXXXXXX'