API docs by Redocly

Pohjola Claim Notification API (3.0.0)

Download OpenAPI specification:Download

Support: verkkotuki@op.fi Terms of Service

Pohjola Claim Notification API allows you to establish a real-time link with Pohjola Insurance.

The API is designed for large and mid-size corporate customers with occupational accidents and diseases insurance at Pohjola Insurance. It simplifies and speeds up the process of reporting accidents.

At the moment, the Claim Notification API can be used to report both occupational and leisure-time accidents. In the future, we will expand the API to cover our other insurance products.

We will continue to develop the API based on feedback, and will release updates regularly.

Release notes

3.0.0 (10/2022)

  • Major changes to required validations

2.2.2 (08/2022)

  • Improve system performance

2.2.1 (08/2022)

  • Text changes

2.2.0 (08/2022)

  • Improve system performance

2.1.0 (06/2022)

  • Allow synonyms for some values
  • Add missing values to enums

2.0.0 (06/2022)

  • Trim redundant commas from BodyPartList enum values

1.3.0 (02/2022)

  • Validation for employment information
  • Bug fixes

1.2.0 (11/2021)

  • Bug fixes
  • Documentation updates

1.1.0 (05/2021)


- Added two new endpoints: Organisation units and Occupation codes. These endpoints can be used to fetch additional details to claim requests.
- Documentation improvements

Security Considerations

HTTP requests to the claims API need to include an SHA-256 calculated hash of the request body. The hash is used to verify the integrity of the data sent between the client and the API. The hash should be set in the Digest header, and it should be calculated using the whole request body. See the example below in the header schema description.

Allowed special characters: ()!'#%&:*+,./?-_@+ and " escaped

Sandbox

Pohjola Claim Notification API is available in sandbox for testing and integration free of charge. To use the API in the sandbox, create a new developer application and use the freshly created API key in your code.

Production access

You can apply for production access while creating a new application. After you create your application, we will contact you for further details. Pohjola Insurance will approve partners whose business model complements its goals.

Do not use the production environment to submit test claims. All claims submitted to the production environment will be considered as valid claims.

If you need to conduct a test in the production environment, please notify your designated contact person at Pohjola Insurance, or verkkotuki@op.fi before sending any test claims. Expressively mark all production test claims as such, e.g. by writing "Test claim" as a value to all free form description fields. Please save any possible claim ID's received from the test claim submission.

Request body structure

Request body has some generic data types which are described here in detail.

Minimum viable example claim

Below is a full example claim depicting the minimum amount of information required for a successful claim

Not having the fields depicted below will result in a failure to process the claim correctly.

Minimum viable example claim: 
{
    "header": {
      "id": {
        "idType": "Uuid",
        "value": "4d88a580-ccc5-4811-b85b-9131d651659f"
      },
      "timeStamp": "2022-01-01T12:12:51.338Z",
      "sender": {
        "id": [
          {
            "value": "2241010-7"
          }
        ],
        "name": "Integrator 1"
      },
      "event": {
        "timeStamp": "2022-01-01T12:12:51.338Z"
      }
    },
    "standardContent": {
      "claimNotification": {
        "claimNotificationDate": "2022-01-08",
        "claimNotificationTime": "12:12",
        "parties": {
          "party": [
            {
              "roleType": "Ilmoittaja",
              "partyIdentifier": [
                {
                  "partyIdentifierType": "Y-tunnus",
                  "value": "7060831-0"
                }
              ],
              "partyOrganisation": {
                "organisationName": "Metsäpalveluyhtiö Brahea TDM",
                "representative": {
                  "partyContact": [
                    {
                      "languageCode": "fi",
                      "telephone": [
                        "0501234567"
                      ],
                      "email": [
                        "testi@email.fi"
                      ]
                    }
                  ],
                  "partyIndividual": {
                    "familyName": "Simmelvuo",
                    "givenName": "Iivo",
                    "name": "Iivo Simmelvuo"
                  },
                  "roleType": "Ilmoittajan edustaja"
                }
              }
            },
            {
              "bank": {
                "bankAccount": {
                  "value": "FI7247838253000036"
                },
                "bankAccountOwnerName": "Metsäpalveluyhtiö Brahea TDM"
              },
              "partyIdentifier": [
                {
                  "partyIdentifierType": "Y-tunnus",
                  "value": "7060831-0"
                }
              ],
              "partyOrganisation": {
                "organisationName": "Metsäpalveluyhtiö Brahea TDM"
              },
              "roleType": "Vakuutuksen ottaja"
            }
          ]
        },
        "reference": {
          "insuranceCompanyReference": [
            {
              "insuranceCompanyReferenceType": "Vakuutustunnus",
              "value": "78-20008-18336-4"
            }
          ],
          "substanceReference": [
            {
                "substanceReferenceType": "Vakuutuksenottajan nimi",
                "value": "Testi esimerkki Yritys Oy"
            },
            {
                "substanceReferenceType": "Vakuutuksenottajan Y-tunnus",
                "value": "8670676-7"
            }
        ]
        },
        "claimIncident": {
          "claimIncidentDescription": [
            {
              "descriptionType": "Tapahtuman kuvaus",
              "value": "Putosin rakennustelineiltä käteni päälle."
            }
          ],
          "incidentLocation": {
            "municipality": "Akaa",
            "municipalityCode": {
              "value": "020"
            },
            "streetAddressLine": [
              "Akaantie 12"
            ]
          },
          "incidentStartDate": "2022-01-08",
          "incidentStartTime": "12:12",
          "parties": {
            "party": [
              {
                "partyContact": [
                  {
                    "languageCode": "fi",
                    "telephone": [
                      "0501234567"
                    ]
                  }
                ],
                "partyIndividual": {
                  "familyName": "Simmelvuo",
                  "givenName": "Iivo",
                  "name": "Iivo Simmelvuo"
                },
                "roleType": "Lisätiedon antaja"
              }
            ]
          }
        },
        "claim": [
          {
            "claimInsurableInterests": {
              "claimInsurableInterest": [
                {
                  "interest": {
                    "personInterest": {
                      "injuryOrIllness": [
                        {
                          "bodyPartList": "Kyynärpää",
                          "bodySideList": "Vasen",
                          "injuryOrIllnessType": "Murtuma"
                        }
                      ],
                      "parties": {
                        "party": [
                          {
                            "bank": {
                              "bankAccount": {
                                "value": "FI0673571173571337"
                              },
                              "bankAccountOwnerName": "Herkko Hägerstrand"
                            },
                            "partyContact": [
                              {
                                "contactUsageList": "Vakituinen osoite",
                                "country": "Suomi",
                                "countryCode": {
                                  "value": "FI"
                                },
                                "postOffice": "Helsinki",
                                "postalCode": "00100",
                                "streetAddressLine": [
                                  "Helsinginkatu 10"
                                ],
                                "telephone": [
                                  "04012345678"
                                ],
                                "email": [
                                  "testi@email.com"
                                ]
                              }
                            ],
                            "partyIdentifier": [
                              {
                                "partyIdentifierType": "Henkilötunnus",
                                "value": "160483-353B"
                              }
                            ],
                            "partyIndividual": {
                              "dateOfBirth": "1965-06-05",
                              "familyName": "Kähö",
                              "givenName": "Herkko",
                              "name": "Herkko Kähö",
                              "occupation": [
                                {
                                  "occupationType": "TV Ammattikoodi",
                                  "value": "43220"
                                },
                                {
                                  "occupationType": "Ammatti",
                                  "value": "Metsuri"
                                }
                              ]
                            },
                            "roleType": "Vahingoittunut"
                          }
                        ]
                      },
                      "statutoryAccidentInterest": {
                        "conditions": {
                          "conditionCode": "31",
                          "travelStartTime": "12:00",
                          "travelDistance": 140,
                          "isNormalRoute": "Ei",
                          "isRouteDeviation": "Kyllä",
                          "travelDescription": "Oltiin matkalla",
                          "travelOriginLocationDescription": "Pori",
                          "travelDestinationLocationDescription": "Myös pori",
                          "meansOfTransportationList": "Henkilöauto",
                          "routeDeviationDescription": [
                            {
                              "routeDeviationDescriptionType": "Kuvaus",
                              "value": "Käytiin välissä Porissa"
                            }
                          ]
                        },
                        "injury": {
                          "disabilityDurationCode": 1,
                          "workEndDate": "2020-03-26",
                          "workEndTime": "16:00",
                          "workStartDate": "2020-03-26",
                          "workStartTime": "08:00",
                          "workingEndedList": "Kyllä"
                        },
                        "employmentInformation": {
                          "isEmploymentValid": "Kyllä"
                        },
                        "employmentType": "Työntekijä",
       
                        "statistics": {
                          "bodyPart": [
                            {
                              "bodyPartCode": "52",
                              "bodySideList": "Vasen"
                            }
                          ],
                          "causeCode": {
                            "causeCodeType": "ESAW",
                            "value": "9999"
                          },
                          "deviationCode": "51",
                          "injuryOrIllnessCode": "020",
                          "injuryTypeCode": "30",
                          "workAssignmentCode": "22",
                          "workEnvironmentCode": "21",
                          "workPerformanceCode": "20"
                        },
                        "trafficAccidentInformation": {
                          "isTrafficAccident": "Ei"
                        }
                      }
                    }
                  },
                  "interestType": "Henkilö"
                }
              ]
            },
            "claimSubType": "Lakisääteinen työtapaturma",
            "claimSubTypeSpecification": "Työtapaturma",
            "claimType": "Tapaturma",
            "incidentCause": {
              "incidentCauseList": "Kaatuminen kompastuessa, liukastuessa tai horjahtaessa"
            }
          }
        ]
      }
    }
  }


Breakdown of different claim sections by section

This section will breakdown in detail all the distinct sections in the order that they appear in the example claim above. Additional documentation for each individual field is provided in the Create claim section below.


The header object is meant to communicate the party sending the claim from a technical standpoint. The identifying information inside is used to track down sent claims and to aid in troubleshooting when problems arise.

To ensure smooth operation and quick help when necessary, the information in the header field should be up to date.


Claim notification parties

The parties object directly in claimNotification is used to communicate the parties not directly involved in the claim, e.g. the parties that haven't been injured, but are still related, like a contact person for the company involved. More detailed descriptions can be found under the general partyType documentation here


Reference

The reference object is used to link the sent claim to a company, both via a valid insurance as well as through name and company ID.

Claim Incident

The claim incident section is used for general information that is present for practically every claim.

Every incident should have a start date and a time, a location and a description. Additionally, claim incident parties object should have a set of valid contact details. More information about the contact party here.

Person Interest

The person interest section is concerned with information required by law for all employee accidents. This section is further broken down into smaller sections.

Injury or Illness

Injury or illness section is used to provide more in depth details on the type of injury or illness related to the event.

The bare minimum requirement is to provide the bodypart affected, the type of injury or illness and the side of the body where applicable. However, where possible, it is advantageous to provide as many details as available, as it will result in a more accurate claim handling process. Naturally all the fields are not always valid, e.g. an illness might not affect a specific bodypart.

It is strongly advised to provide an answer to every field in this object when possible.

In the case of death, an injuryOrIllness description should be provided with descriptionType Vakavuusluokka and value Kuollut

Death example: 
{
  "injuryOrIllnessDescription": 
  [
      { "descriptionType": "Vakavuusluokka",
        "value": "Kuollut"
      }
  ]
}

Person Interest Parties

The parties object inside person interest should only have one party, the injured person with the roletype Vahingoittunut, more details here.

Statutory Accident Interest

Statutory accident interest holds detailed information regarding the exact conditions and circumstances of the incident. These answers are required by law and are often dependent on eachother.

  • Conditions The conditions object contains information required by law about the conditions of the incident. The values inside are provided as numerical codes as described by TVK. Further documentation can be found at: https://www.tvk.fi/korvaaminen/tyotapaturma/

The structure of the object is dependent on the primary mandatory field conditionCode. The rest of the fields inside the object are mandatory based on the value provided for conditionCode.

  • If conditionCode is set to 11, corresponding to at work, naturally fields to do with traveling to work are not relevant and do not have to be filled, but the field performDescription becomes mandatory, as it is related.
  • If conditionCode is set to 12, a code that corresponds to traveling, all the fields related to traveling, e.g. travelDescription, travelOriginLocationDescription now become mandatory, whereas the field performDescription, as it is not related to the code 12, is no longer mandatory.

Further documentation describing all the relationships is provided below.

  • Injury The injury object provides details between the employment and the injury. It is used to convey how the incurred incident affects the employee and the employer.

  • EmploymentInformation The employmentInformation object inside statutoryAccidentInterest has a dependency on the injury object's field disabilityDurationCode.

    • If disabilityDurationCode is set to 1, only the field isEmploymentValid inside employmentInformation is required.
    • If disabilityDurationCode is set to 2 or 3, all the fields inside employmentInformation are required, except parties and employmentEndDate.
    • If isEmploymentValid is set to Ei, employmentEndDate is required. Otherwise, employmentEndDate is not required.

  • Statistics The statistics object is alongside conditions used for information required by law. Some of the information required is also presented in other parts of the claim, e.g. the bodypart information is required here and in earlier in injuryOrIllness section by design. As with conditions object, the values inside statistics object are mostly provided as numerical codes. Further documentation can be found at: https://www.tvk.fi/korvaaminen/tyotapaturma/

It is strongly advised to provide an answer to every field in this object wherever possible.

Example: 
{
  "statutoryAccidentInterest": {
    "conditions": {
      "conditionCode": "31",
      "travelStartTime": "12:00",
      "travelDistance": 140,
      "isNormalRoute": "Ei",
      "isRouteDeviation": "Kyllä",
      "travelDescription": "Oltiin matkalla",
      "travelOriginLocationDescription": "Pori",
      "travelDestinationLocationDescription": "Myös pori",
      "meansOfTransportationList": "Henkilöauto",
      "routeDeviationDescription": [
        {
          "routeDeviationDescriptionType": "Kuvaus",
          "value": "Käytiin välissä Porissa"
        }
      ]
    },
    "employmentInformation": {
      "isEmploymentValid": "Ei",
      "employmentValidityType": "Toistaiseksi",
      "employmentStartDate": "2020-02-02",
      "employmentEndDate": "2020-04-02",
      "occupationType": "Päätoimi",
      "isCalledToWorkIfNeeded": "Ei",
      "permanentJobAddress": {
        "postOffice": "Town/city e.g. Helsinki",
        "postalCode": "00330",
        "streetAddressLine": "Kujakajukuja 1"
      }
    },
    "injury": {
      "disabilityDurationCode": 1,
      "isWorkPreventer": "Ei",
      "notifiedToEmployerDate": "2020-03-26",
      "workEndDate": "2020-03-26",
      "workEndTime": "16:00",
      "workStartDate": "2020-03-26",
      "workStartTime": "08:00",
      "workingEndedList": "Kyllä"
    },
    "statistics": {
      "bodyPart": [
        {
          "bodyPartCode": "52",
          "bodySideList": "Vasen"
        }
      ],
      "causeCode": {
        "causeCodeType": "ESAW",
        "value": "9999"
      },
      "deviationCode": "51",
      "injuryOrIllnessCode": "020",
      "injuryTypeCode": "30",
      "workAssignmentCode": "22",
      "workEnvironmentCode": "21",
      "workPerformanceCode": "20"
    },
    "trafficAccidentInformation": {
      "isTrafficAccident": "Ei"
    }
  }
}

partyType

partyType is a data type which describes parties related to the claim, but as it is generic, it includes a lot of fields that do not need to be filled in all cases. The properties required for each different party related to the claim are documented here

1. Injured person

Details of the injured person.

JSON path: standardContent.claimNotification.claim.claimInsurableInterests.claimInsurableInterest[].interest.personInterest.parties.party

Required fields:

  • roleType must be Vahingoittunut

  • bank must include injured person's bank account where possible compensation will be paid

  • partyContact must include injured person's contact details

    • contactUsageList should be set to Vakituinen osoite.
    • streetAddressLine, municipality and postalCode are all validated to have values.

  • partyIdentifier must include injured person's social security number, if applicable

  • dateOfBirth must always be present

  • partyIndividual must include injured person's date of birth, names and occupation details

  • The occupation details fetched from the Occupation Codes API should be included here in occupation array. Occupation code refers to occupation with occupationType TV Ammattikoodi and occupation name refer to occupation with occupationType Ammatti.

Example: 
{
  "bank": {
    "bankAccount": {
      "value": "FI0673571173571337"
    },
    "bankAccountOwnerName": "Herkko Hägerstrand"
  },
  "partyContact": [
    {
      "contactUsageList": "Vakituinen osoite",
      "country": "Suomi",
      "countryCode": {
        "value": "FI"
      },
      "postOffice": "Helsinki",
      "postalCode": "00100",
      "streetAddressLine": [
        "Helsinginkatu 10"
      ],
      "telephone": [
        "04012345678"
      ],
      "email": [
        "testi@email.com"
      ]
    }
  ],
  "partyIdentifier": [
    {
      "partyIdentifierType": "Henkilötunnus",
      "value": "160483-353B"
    }
  ],
  "partyIndividual": {
    "dateOfBirth": "1965-06-05",
    "familyName": "Kähö",
    "givenName": "Herkko",
    "name": "Herkko Kähö",
    "occupation": [
      {
        "occupationType": "TV Ammattikoodi",
        "value": "43220"
      },
      {
        "occupationType": "Ammatti",
        "value": "Timpuri"
      }
    ]
  },
  "roleType": "Vahingoittunut"
}


2. Reporting party

Details of the party reporting the claim.

JSON path: standardContent.claimNotification.parties.party

Required fields:

  • roleType must be Ilmoittaja
  • partyIdentifier must include the business ID of the reporting company
  • partyOrganisation must include company's name and company representative's name, and contact details
    • representative roleType must be Ilmoittajan edustaja
    • representative contact details, telephone and email, must be provided
Example: 
{
  "roleType": "Ilmoittaja",
  "partyIdentifier": [
    {
      "partyIdentifierType": "Y-tunnus",
      "value": "7060831-0"
    }
  ],
  "partyOrganisation": {
    "organisationName": "Metsäpalveluyhtiö Brahea TDM",
    "representative": {
      "partyContact": [
        {
          "languageCode": "fi",
          "telephone": [
            "0501234567"
          ],
          "email": [
            "testi@email.fi"
          ]
        }
      ],
      "partyIndividual": {
        "familyName": "Simmelvuo",
        "givenName": "Iivo",
        "name": "Iivo Simmelvuo"
      },
      "roleType": "Ilmoittajan edustaja"
    }
  }
}


3. Policyholder

Details of the company in whose name an insurance policy is held.

JSON path: standardContent.claimNotification.parties.party

Required fields:

  • roleType must be Vakuutuksen ottaja
  • bank must include policyholder's bank account
  • partyIdentifier must include policyholder's business ID
  • partyOrganisation must include policyholder's organisation name and optionally organisation unit
  • The organisation unit code fetched from the Organisation Units API should be included here as the department value.
Example: 
{
  "bank": {
    "bankAccount": {
      "value": "FI7247838253000036"
    },
    "bankAccountOwnerName": "Metsäpalveluyhtiö Brahea TDM"
  },
  "partyIdentifier": [
    {
      "partyIdentifierType": "Y-tunnus",
      "value": "7060831-0"
    }
  ],
  "partyOrganisation": {
    "organisationName": "Metsäpalveluyhtiö Brahea TDM",
    "department": {
      "value": "3200000000000"
    }
  },
  "roleType": "Vakuutuksen ottaja"
}


4. Contact

Contact Details of the people who can provide information about the claim

JSON path: standardContent.claimNotification.claimIncident.parties.party

Required fields:

  • roleType must be Lisätiedon antaja
  • partyContact must include contact information
  • partyIndividual must include contact's name
Example: 
{
  "partyContact": [
    {
      "languageCode": "fi",
      "telephone": [
        "0501234567"
      ]
    }
  ],
  "partyIndividual": {
    "familyName": "Simmelvuo",
    "givenName": "Iivo",
    "name": "Iivo Simmelvuo"
  },
  "roleType": "Lisätiedon antaja"
}


#### 5. Party who paid expenses

Details of the parties who paid expenses related to the claim.

JSON path: standardContent.compensationDemand[].parties.party

Required fields:

  • roleType must be Maksun saaja
  • bank must include bank account where possible compensation will be paid
  • partyIdentifier must include:
    • social security number, if an individual paid the expense
    • business ID, if a company paid the expense
  • partyIndividual must include payer name only if the expense was paid by an individual
  • partyOrganisation must include company name only if the expense was paid by a company

Example for a company: 
{
  "bank": {
    "bankAccount": {
      "value": "FI7247838253000036"
    },
    "bankAccountOwnerName": "Rakennusliike Oy"
  },
  "partyIdentifier": [
    {
      "partyIdentifierType": "Y-tunnus",
      "value": "4539371-7"
    }
  ],
  "partyOrganisation": {
    "organisationName": "Rakennusliike Oy"
  },
  "roleType": "Maksun saaja"
}

Example for a person: 
{
  "bank": {
    "bankAccount": {
      "value": "FI0673571173571337"
    },
    "bankAccountOwnerName": "Ville Vahingoittunut"
  },
  "partyIdentifier": [
    {
      "partyIdentifierType": "Henkilötunnus",
      "value": "050665-0138"
    }
  ],
  "partyIndividual": {
    "name": "Ville Vahingoittunut"
  },
  "roleType": "Maksun saaja"
}


Claims

Create claim

Submits insurance claim request.

Authorizations:
None
header Parameters
Accept
required
string
Value: "application/json"
Content-Type
required
string
Value: "application/json"
Digest
required
string
Example: SHA-256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

SHA-256 calculated hash of the request body

x-client-request-id
string <uuid>
Example: 7dc53df5-123e-49b3-8670-b1c468f47f1f

Unique identifier (UUID) for a specific request / request flow through the whole system / software stack.

Request Body schema: application/json
required
object (HeaderType)

Metadata related to claim sending process and the sending party

required
object (StandardContentType)

All information related to the claim object being sent to the insurance company

Responses

Request samples

Content type
application/json
{
  • "header": {
    },
  • "standardContent": {
    }
}

Response samples

Content type
application/json
{
  • "isSandbox": true
}

Occupation codes

Get occupation codes

Returns a list of occupation codes belonging to a specified policy. When the company has no occupation codes, an empty list is returned. If any occupation codes are returned, one should be selected and included in the claim being submitted.

Authorizations:
None
header Parameters
Content-Type
required
string
Value: "application/json"
x-client-request-id
string <uuid>
Example: 7dc53df5-123e-49b3-8670-b1c468f47f1f

Unique identifier (UUID) for a specific request / request flow through the whole system / software stack.

Request Body schema: application/json
policyCode
string

A valid Pohjola insurance ID

companyId
string

A valid Finnish Business ID

searchDate
string <date>

An optional date in ISO Date format, used if reporting events for organisation units that are no longer used. By default uses current date

Responses

Request samples

Content type
application/json
{
  • "policyCode": "78-20005-00005-9",
  • "companyId": "8434815-0",
  • "searchDate": "2021-04-28"
}

Response samples

Content type
application/json
[
  • {
    }
]

Organisation units

Get organisation units

Returns a list of organisation unit names and codes belonging to a specified policy. When the company has no organisation units, an empty list is returned. If any organisation units are returned, one should be selected and its code included in the claim being submitted.

Authorizations:
None
header Parameters
Content-Type
required
string
Value: "application/json"
x-client-request-id
string <uuid>
Example: 7dc53df5-123e-49b3-8670-b1c468f47f1f

Unique identifier (UUID) for a specific request / request flow through the whole system / software stack.

Request Body schema: application/json
policyCode
string

A valid Pohjola insurance ID

companyId
string

A valid Finnish Business ID

searchDate
string <date>

An optional date in ISO Date format, used if reporting events for organisation units that are no longer used. By default uses current date

Responses

Request samples

Content type
application/json
{
  • "policyCode": "78-20005-00005-9",
  • "companyId": "8434815-0",
  • "searchDate": "2021-04-28"
}

Response samples

Content type
application/json
[
  • {
    }
]