User Domicile Information

User Domicile is information that applies only to Finnish users — it's about their current home municipality (kotikunta).

Domicile information is stored at User and Legal levels. User-level information is modifiable, and can be used to store information provided by the user or other sources. Legal-level information is sourced from DVV (or Suomi.fi) and isn't otherwise modifiable.

When a user's municipality is known, the domicile code is usually available. If the user has an active protection order, code may be unavailable while domicile classes still have values. If no domicile information is available at all, code is missing (or null) and classes is missing or an empty array.

Reading Domicile information

Domicile information can be read through the Management API, the UserInfo endpoint, and the Management UI's Account editor.

Management API

Example User-level information request:

GET /api/rest/v1/user/{userId}

Example response:

{
  ...,
  "domicile": {
    "names": {
      "fi": "Turku",
      "sv": "Åbo"
    },
    "code": "853",
    "classes": [
      "central_pricing"
    ],
    "movedInDate": "2023-09-18",
    "movedOutDate": "2023-09-18"
  },
  "temporaryDomicile": {
    "names": {
      "fi": "Turku",
      "sv": "Åbo"
    },
    "code": "853",
    "classes": [
      "central_pricing"
    ],
    "movedInDate": "2023-09-18",
    "movedOutDate": "2023-09-18"
  },
  ...
}

The response contains domicile and temporaryDomicile objects, for kotikunta (domicile) and tilapäinen kunta (temporary domicile) respectively.

Example Legal-level information request:

GET /api/rest/v1/user/{userId}/legal

Example response:

{
  ...
  "domicile": {
    "names": {
      "fi": "Turku",
      "sv": "Åbo"
    },
    "code": "853",
    "classes": [
      "central_pricing"
    ],
    "movedInDate": "2023-09-18",
    "movedOutDate": "2023-09-18"
  },
  "temporaryDomicile": {
    "names": {
      "fi": "Turku",
      "sv": "Åbo"
    },
    "code": "853",
    "classes": [
      "central_pricing"
    ],
    "movedInDate": "2023-09-18",
    "movedOutDate": "2023-09-18"
  },
  "formerDomiciles": [
    {
      "names": {
        "fi": "Turku",
        "sv": "Åbo"
      },
      "code": "853",
      "classes": [
        "central_pricing"
      ],
      "movedInDate": "2023-09-18",
      "movedOutDate": "2023-09-18"
    }
  ],
  ...
}

The same objects are returned in the same format, plus a formerDomiciles array, if available.

UserInfo endpoint

Domicile information is provided via the domicile claim, requested using the address scope during OIDC authentication. Legal-level domicile information additionally requires the https://oneportal.trivore.com/scope/legalinfo.readonly scope.

Example claim content:

{
  "userDomicile" : {
    "names" : {
      "sv" : "Åbo",
      "fi" : "Turku"
    },
    "code" : "853",
    "classes" : [ "turun-seutu" ]
  },
  "userTemporaryDomicile" : {
    "names" : {
      "sv" : "S:t Karins",
      "fi" : "Kaarina"
    },
    "code" : "202",
    "classes" : [ "turun-seutu" ]
  },
  "legalDomicile" : {
    "names" : {
      "sv" : "Helsingfors",
      "fi" : "Helsinki"
    },
    "code" : "91",
    "classes" : [ "pkseutu" ]
  },
  "legalTemporaryDomicile" : {
    "names" : {
      "sv" : "Vanda",
      "fi" : "Vantaa"
    },
    "code" : "92",
    "classes" : [ "pkseutu" ]
  }
}

The claim contains both User- and Legal-level information, in the same format the Management API provides it in.

Management UI

User-level domicile information, including the Temporary Domicile, can be viewed and modified on the User editor's Extra tab.

Legal-level domicile information can be viewed on the Legal tab.