Managing funerals (Structured API)

This page describes the new recommended workflow for managing funerals using structured data with the petition endpoints.

Overview of the Workflow

Both funeral homes and graveyard authorities manage funerals following these steps:

1. Establish a funeral responsible (prerequisite)
2. Gather and submit structured funeral petition data
3. Update the petition data as needed

1. Establish a Funeral Responsible (Prerequisite)

Before using the structured data API, you must establish a funeral responsible by:

1. Doing a funeral lookup
2. Attaching a next-of-kin to the funeral if needed
3. Creating a responsibility statement
4. Having it signed through the Altinn form

Follow steps 1-3 in the Legacy Workflow to establish a funeral responsible.

2. Retrieve Type Definitions

Before submitting funeral petition data, you should retrieve information about grave types and rite types to ensure your data is structured correctly:

• GET /dgm/api/v1/definitions/grave-types - Returns a list of grave type definitions with their attributes
• GET /dgm/api/v1/definitions/rite-types - Returns a list of rite type definitions

These endpoints provide the necessary metadata to construct a valid funeral petition, including: - Valid codes for grave and rite types - Required attributes for each type - Expected data types for attributes

Example response from GET /dgm/api/v1/definitions/grave-types:

[
  {
    "code": "STANDARD_GRAVE",
    "name": "Standard Grave",
    "deprecatedFrom": null,
    "expectedAttributes": [
      {
        "key": "depth",
        "expectedType": "number",
        "isRequired": true
      },
      {
        "key": "graveSize",
        "expectedType": "string",
        "isRequired": true
      }
    ]
  }
]

3. Retrieve Existing Petition Data (If Available)

To get existing petition data for a party:

• GET /dgm/api/v1/funeral-petitions/{partyId} - Returns the current petition data for the specified party if available

This can be useful when you need to display or modify existing petition information. The endpoint will return 404 Not Found if no funeral responsible is set for the requested party.

4. Submit a Funeral Petition

Instead of uploading unstructured attachments, you can now submit structured data for a funeral petition:

• POST /dgm/api/v1/funeral-petitions - Submit structured data for a funeral petition

The petition data structure includes: - Responsibility statement information (funeral home, place of death, etc.) - Cremation or coffin burial details - Grave information - Rite details

Example request for POST /dgm/api/v1/funeral-petitions:

{
  "partyId": "00000000-0000-0000-0000-000000000000",
  "data": {
    "responsibilityStatement": {
      "funeralHomeId": "12345",
      "allowFuneralHomeToContactNextOfKin": true,
      "placeOfDeathLocationId": "0301",
      "hasNotifiedNextOfKin": true,
      "cremation": {
        "ashHandling": "BURIAL",
        "urnBurialLocationId": "0301",
        "crematoriumId": "12345",
        "urnProvider": "FUNERAL_HOME",
        "hasAshSpreadingPermit": false
      }
    },
    "grave": {
      "type": "STANDARD_GRAVE",
      "attributes": {
        "depth": 2,
        "graveSize": "single"
      }
    },
    "rites": [
      {
        "type": "MEMORIAL_SERVICE",
        "location": "Oslo Cathedral",
        "dateTime": "2025-06-01T14:00:00Z"
      }
    ]
  }
}

This structured approach allows for better data validation and more efficient processing compared to the attachment-based approach. The request will be denied with a 403 Forbidden status if the specified party is not the funeral responsible.

4.1 Different Processing Workflows for Each Data Component

Responsibility Statement Data: - Requires user confirmation/signature in Altinn - Changes to responsibility statement data submitted through the petition endpoint will initiate a new signing workflow for the user - Data is not considered official until signed by the user - This process may take time to complete depending on when the user signs

Grave Data: - Also requires approval through a separate workflow - Changes to grave data will not be immediately official - Processing and approval may take some time

Rites Data: - Processed immediately without additional approvals - Changes to rites are applied directly after submission - No user confirmation loop is required

4.2 Implications for Integration

When designing your integration:

1. Status Tracking: Plan to monitor the status of each component separately
2. User Experience: Inform users about which parts of their petition are immediately active and which require further approval
3. Event Handling: Subscribe to events to be notified when each component completes its workflow
4. Retrieval Strategy: When retrieving petition data, check the status of each component to determine what data is officially approved

5. Upload Additional Attachments

If there are any additional attachments specific to the party, like a declaration or an ash spreading permit, these can be uploaded by calling the POST dgm/api/funeral-home/attachments endpoint. The attachment will be linked to the party.