Tekninen kuvaus Huoneistotietojen kyselypalvelu isännöintijärjestelmille (REST)
Yhteys palvelun ja asiakkaan välillä on SSL-suojattu (Secure Socket Layer, HTTPS-protokolla). Palveluun pitää kirjautua sisään antamalla käyttäjätunnus ja salasana. Käytössä on HTTP Basic Authentication -tunnistus, jonka on oltava mukana jokaisessa pyynnössä. Palvelu kerää hakuihin liittyviä tilasto- ja laskutustietoja palvelupyyntöjen perusteella käyttäjätunnuksittain jaoteltuna.
JSON-rakenne pyydetään palvelusta HTTPS/POST-protokollaan perustuvalla kyselyllä. Kyselyyn sisältyvät parametrit, joiden mukaista tietoa haetaan.
Rajapintapalvelun skeemojen osalta on huomioitava, että rajapinnasta palautuvaan tietoon voi tulla uusia kenttiä uusissa sovellusversioissa. Muutoksista pyritään tiedottamaan hyvissä ajoin, mutta integraatiototeutusten on hyvä olla sellaisia, että ne sietävät uusia kenttiä tietomallissa ja osaavat jättää ne huomiotta.
Aineistot ja tuotteet
Tuotteet
- Yhtiön perustiedot
- Osakeryhmien haku hakuehdoin
- Osakeryhmän perustiedot
- Osakeryhmän hallintakohteet
- Osakeryhmän yhteystiedot
- Osakeryhmän rajoitukset (sis. vain osakeluetteloon merkityt rajoitukset)
- Osakeryhmän rajoitukset, UUSI (Suppea ja Laaja)
- Osakeryhmän omistajat (Suppea ja Laaja)
- Osakeryhmien muutostiedot
- Yhtiön osakkaiden yhteystiedot
- Koodistot
- Tiedotteet
- Valtuutusavaimet
Tuotteiden yhteiset
- Skeemat (päivitetty 15.4.2025)
- Koodistot (päivitetty 10.3.2025)
- Huom. pdf-tiedoston ylläpito on lopetettu ja se poistetaan 27.5.2025. Ajantasaiset koodistot ovat saatavissa koodistot-rajapinnasta.
- Tietojen kuvaukset (päivitetty 15.4.2025)
Kyselyt ja esimerkit
Yhtiön perustiedot
Rakenteessa esitetään huoneistotietojärjestelmän tulosteiden osiossa "Yhtiö" esiintyvät tiedot. Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta yhtiöstä.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/yhtiot/perustiedot
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnus": "0161649-9"
}
Osakeryhmien haku hakuehdoin
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta yhtiöstä. Rakenteessa esitetään osakeryhmien suppeat perustiedot jokaisesta yhtiön voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä.
Tällä kyselyllä saadaan tietää, perustuuko osakeryhmän omistus huoneistotietojärjestelmään rekisteröityyn sähköiseen merkintään. Vastauksessa palautetaan tieto 'sahkoinenOmistusmerkinta' arvolla true, jos omistus perustuu sähköiseen merkintään, ja arvolla false, jos omistus perustuu osakekirjaan tai osakkeen muotoa ei ole vielä vahvistettu.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/haku
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnus": "0161649-9"
}
Esimerkkivastaus lakannut osakeryhmä
Osakeryhmän perustiedot
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä.
Rakenteessa esitetään huoneistotietojärjestelmän tulosteiden osiossa "Osakeryhmä" esiintyvät tiedot.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. |
| osakeryhmatunnus | osakeryhmätunnus | 1 | Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/perustiedot
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnus": "0161649-9",
"osakeryhmatunnus" : "OH5BRDQ22L3NBB12"
}
Esimerkkivastaus voimassa oleva
Esimerkkivastaus aikaisempi osakeryhmätunnus
Osakeryhmän hallintakohteet
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta, syntyvästä tai lakkaavasta osakeryhmästä.
Rakenteessa esitetään osakeryhmällä hallinnoitavien tilojen (huoneisto, autopaikka, muu tila) tiedot.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. Vain asunto-osakeyhtiöt ja keskinäiset kiinteistöosakeyhtiöt voivat kuulua huoneistotietojärjestelmään. |
| osakeryhmatunnus | osakeryhmätunnus | 1 | Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/hallintakohteet
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnus": "0161649-9",
"osakeryhmatunnus" : "OH5BRDQ22L3NBB12"
}
Esimerkkivastaus voimassa oleva
Osakeryhmän yhteystiedot
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta, syntyvästä tai lakkaavasta osakeryhmästä.
Rakenteessa esitetään osakeryhmän jokaisen voimassa olevan omistajan omistusosuus. Omistus voi olla merkitty useana eri osuutena, jolloin jokainen osuus esitetään erillisenä. Rakenteessa esitetään omistajien yhteystiedot sekä tieto siitä, onko omistaja merkitty osakeluetteloon.
Jos omistajalla on huoneistotietojärjestelmässä henkilötunnus tai y-tunnus ja omistaja on ilmoittanut huoneistotietojärjestelmään VTJ:stä/YTJ:stä poikkeavan osoitteen, esitetään se, ja muussa tapauksessa esitetään ajantasainen VTJ:n/YTJ:n mukainen osoite. Kuolleen henkilön VTJ-osoitetta ei esitetä, mutta mahdollinen poikkeava osoite esitetään. Ulkomainen osoite voidaan esittää kahdella vaihtoehtoisella tavalla: joko elementeissä katuosoite, postinumero, postitoimipaikka ja osoitteenMaa, tai elementeissä katuosoite ja osoitteenMaa.
Tietojen luovutuskiellossa olevasta osakkeen omistajasta palautetaan osoitteen osalta vain omistajan erikseen taloyhtiötä varten ilmoittama sähköpostiosoite ja/tai Väestötietojärjestelmästä poikkeava osoite.
Jos henkilölle ei ole Maanmittauslaitoksessa tallennettu erikseen taloyhtiötä varten ilmoitettua osoitetta, ei omistajan osalta osoitetietoja palauteta.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. |
| osakeryhmatunnus | osakeryhmätunnus | 1 | Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/yhteystiedot
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnus": "0161649-9",
"osakeryhmatunnus" : "OH5BRDQ22L3NBB12"
}
Esimerkkivastaus (postiosoite ja sähköpostiosoite)
Esimerkkivastaus (henkilö/yritys tunnuksellisena/tunnuksettomana)
Esimerkkivastaus (samalla omistajalla useita omistusosuuksia)
Esimerkkivastaus (osaomistajalla turvakielto eikä erikseen taloyhtiötä varten ilmoitettua osoitetta)
Käyttötapaukset
Uuden omistajan tiedot asiakasjärjestelmään
Yhtiön osakkaiden yhteystiedot
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta tai lakkaavasta yhtiöstä. Kyselyssä palautetaan yhtiön voimassa olevista, syntyvistä tai lakkaavista osakeryhmistä vastaavat tiedot kuin osakeryhmien yhteystietojen kyselyssä.
Rakenteessa esitetään osakeryhmien jokaisen voimassa olevan omistajan omistusosuus. Omistus voi olla merkitty useana eri osuutena, jolloin jokainen osuus esitetään erillisenä. Rakenteessa esitetään omistajien yhteystiedot sekä tieto siitä, onko omistaja merkitty osakeluetteloon.
Jos omistajalla on huoneistotietojärjestelmässä henkilötunnus tai y-tunnus ja omistaja on ilmoittanut huoneistotietojärjestelmään VTJ:stä/YTJ:stä poikkeavan osoitteen, esitetään se, ja muussa tapauksessa esitetään ajantasainen VTJ:n/YTJ:n mukainen osoite. Kuolleen henkilön VTJ-osoitetta ei esitetä, mutta mahdollinen poikkeava osoite esitetään. Ulkomainen osoite voidaan esittää kahdella vaihtoehtoisella tavalla: joko elementeissä katuosoite, postinumero, postitoimipaikka ja osoitteenMaa, tai elementeissä katuosoite ja osoitteenMaa.
Tietojen luovutuskiellossa olevasta osakkeen omistajasta palautetaan osoitteen osalta vain omistajan erikseen taloyhtiötä varten ilmoittama sähköpostiosoite ja/tai Väestötietojärjestelmästä poikkeava osoite.
Jos henkilölle ei ole Maanmittauslaitoksessa tallennettu erikseen taloyhtiötä varten ilmoitettua osoitetta, ei omistajan osalta osoitetietoja palauteta.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/yhtiot/yhteystiedot
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnus": "7527575-4"
}
Osakeryhmän rajoitukset
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta, syntyvästä tai lakkaavasta osakeryhmästä.
Rakenteessa esitetään osakeryhmällä voimassa olevista rajoituksista ne, jotka esitetään osakeluettelossa:
- Lesken hallintaoikeus
- Testamenttiin perustuva käyttöoikeus
- Vuokra-asuntolainojen ja asumisoikeustalolainojen korkotuesta annetun lain mukainen merkintä
- Vuokratalojen rakentamislainojen lyhytaikaisesta korkotuesta annetun lain mukainen merkintä
- Aravalain mukainen merkintä
- Yhtiöjärjestyksestä johtuva lunastusrajoitus
- Yhtiöjärjestyksestä johtuva muu vaihdannanrajoitus
- Aravarajoituslain mukainen merkintä
- Ulosmittaus
- Turvaamistoimi
- Väliaikainen turvaamistoimi
- Takavarikko
- Vakuustakavarikko
- Väliaikainen vakuustakavarikko
- Väliaikaistoimi
- Kuolinpesäosuuden ulosmittaus
- Yhtiöosuuden ulosmittaus
- Luovutus- ja panttauskielto
Rajoitukseen liittyvät henkilöt esitetään myös henkilöiden osalta joilla on tietojen luovutuskielto.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. |
| osakeryhmatunnus | osakeryhmätunnus | 1 | Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/rajoitukset
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnus": "0161649-9",
"osakeryhmatunnus" : "OH5BRDQ22L3NBB12"
}
Osakeryhmän rajoitukset, UUSI
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä. Rakenteessa esitetään osakehuoneistotulosteen osioissa "Vallintarajoitukset" ja "Muut rajoitukset" esiintyvät tiedot. Osakehuoneistotulosteen kuvauksen löydät täältä
Kyselyssä palautetaan kaikki osakeryhmälle merkityt rajoitukset tilassa: vireillä, voimassa oleva, ei lainvoimaiset ratkaisut.
Kyselyssä palautetaan tiedot myös mahdollisista vireillä olevista rajoituksen korjaamisista ja poistamisasioista. Mikäli osakkeen muoto on edelleen osakekirja, palautetaan tästä tieto kyselyssä koodistolla osakeryhman_huomio koodiarvolla 2
Tuotteesta on saatavilla suppea ja laaja versio. Suppeassa palautetaaan henkilöstä nimi, syntymäaika ja mahdollinen kuolinpäivä. Laajassa palautetaan henkilöstä nimi, henkilötunnus ja mahdollinen kuolinpäivä
Rajoitukseen liittyvät henkilöt esitetään myös henkilöiden osalta joilla on tietojen luovutuskielto.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. Vain asunto-osakeyhtiöt ja keskinäiset kiinteistöosakeyhtiöt voivat kuulua huoneistotietojärjestelmään. |
| osakeryhmatunnus | osakeryhmätunnus | 1 | Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava. |
Esimerkit
Suppea:
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/rajoitukset-suppea
POST:
{
"valtuutusavaimet": ["HTJ-2021-11-16-dcc4f393-1a16-486d-895f-83d686ac6ba3"],
"ytunnus": "5063373-8",
"osakeryhmatunnus": "OH62HZN2H99QM557"
}
Laaja:
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/rajoitukset-laaja
POST:
{
"valtuutusavaimet": ["HTJ-2021-11-16-dcc4f393-1a16-486d-895f-83d686ac6ba3"],
"ytunnus": "6116537-8",
"osakeryhmatunnus": "OHPS2FUFRXS48R73"
}
Esimerkkivastaus osakeluettelon siirrossa ilmoitettu rajoitus
Esimerkkivastaus hakemuksesta tehty rajoitusmerkintä
Esimerkkivastaus rajoitus vireillä
Esimerkkivastaus kun osakeryhmän tila syntyvä
Osakeryhmän omistajat
Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä. Rakenteessa esitetään osakehuoneistotulosteen osiossa "Omistusoikeudet" esiintyvät tiedot. Osakehuoneistotulosteen kuvauksen löydät täältä
Kyselyssä palautetaan kaikki osakeryhmälle rekisteröidyt omistukset tilassa: vireillä, voimassa oleva, ehdollinen, ei lainvoimaiset ratkaisut sekä tieto mahdollisesti vireillä olevasta omistuksen korjaamisesta.
Tuotteesta on saatavilla suppea ja laaja versio. Suppeassa palautetaaan henkilöstä nimi, syntymäaika ja mahdollinen kuolinpäivä. Laajassa palautetaan henkilöstä nimi, henkilötunnus ja mahdollinen kuolinpäivä
Tietojen luovutuskiellossa olevasta osakkeen omistajasta palautetaan kaikki vastaavat tiedot kuin " ei tietojen luovutuskiellossa" olevasta omistajasta.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnus | y-tunnus | 1 | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. Vain asunto-osakeyhtiöt ja keskinäiset kiinteistöosakeyhtiöt voivat kuulua huoneistotietojärjestelmään. |
| osakeryhmatunnus | osakeryhmätunnus | 1 | Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava. |
Esimerkit
Suppea:
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/omistajat-suppea
POST:
{
"valtuutusavaimet": ["HTJ-2021-11-16-dcc4f393-1a16-486d-895f-83d686ac6ba3"],
"ytunnus": "5063373-8",
"osakeryhmatunnus": "OHXPPQMXD6U3P243"
}
Laaja:
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/omistajat-laaja
POST:
{
"valtuutusavaimet": ["HTJ-2021-11-16-dcc4f393-1a16-486d-895f-83d686ac6ba3"],
"ytunnus": "5063373-8",
"osakeryhmatunnus": "OHXPPQMXD6U3P243"
Esimerkkivastaus omistuksen rekisteröinti hyväksytty (sisältää myös esimerkin omistuksen korjaamisen tiedosta)
Esimerkkivastaus omistuksen rekisteröinti ehdollinen (kysely sisältää myös luovuttajatiedon)
Esimerkkivastaus omistuksen rekisteröinti vireillä
Esimerkkivastaus omistuksen rekisteröinti turvakielto (Kyselyssä ei palauteta henkilötietoja)
Esimerkkivastaus omistuksen rekisteröinti kuolinpesä (Kyselyssä palautetaan kuolinpesä henkilö ja kuolinpesän osakkaat)
Esimerkkivastaus kun osakeryhmän tila syntyvä
Osakeryhmien muutostiedot
Rakenteessa esitetään tunnistetiedot muutoksista, joita yhtiöiden osakeryhmillä on aikavälillä (max 31 päivää) tapahtunut. Tiedot voidaan pyytää huoneistotietojärjestelmässä voimassa olevista yhtiöistä.
Rakenteessa esitetään muutostapahtuma jokaisesta yhtiön osakeryhmälle aikavälillä tapahtuneesta
- Perustajaosakkaan tallentamisesta
- Lainvoimaisesti hyväksytystä omistuksen kirjaamisesta
- Osakeluetteloon merkitsemisestä
- Lainvoimaisesti hyväksytystä rajoituksen merkitsemisestä
- Lainvoimaisesti hyväksytystä rajoituksen poistamisesta
- Huoneistotietojärjestelmään tallennetun osoitteen/sähköpostin lisäys tai muutos tai poisto (Huom! ei koske osakkaan vtj osoitteen muutoksia)
- Omistuksen rekisteröinnistä osakeluettelossa olevalle omistajalle
- Osakkeen muodon muuttamisesta (Huom! Koskee vain tilanteita, kun osakkeen muoto "määrittämätön" vahvistetaan joko sähköiseksi merkinnäksi tai osakekirjaksi)
Kyselyparametrit
| Nimi | Arvot | Lkm | Oletusarvo | Kuvaus |
| limit | nro | 0..1 | 10 | Vastauksessa palautettavien tulosten määrä. Tulosten kokonaislukumäärän saa vastaussanoman TotalElements-kentästä. |
| page | nro | 0..1 | 0 | Vastauksessa palautettavan sivun numero. Ensimmäinen sivu on 0. Sivujen kokonaislukumäärän saa vastaussanoman TotalPages-kentästä. |
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
| ytunnukset | y-tunnus | 1..n | Yhtiön y-tunnus. Yhtiön pitää olla joko uusi vuonna 2019 tai myöhemmin perustettu yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. |
| alkupvm | pvm | 1 | Aikavälin alkupvm. Palvelu palauttaa myös annettuna päivänä tapahtuneet muutokset. Aikavälin (alkupvm...loppupvm) maksimipituus on 31 päivää. |
| loppupvm | pvm | 1 | Aikavälin loppupvm. Palvelu palauttaa myös annettuna päivänä tapahtuneet muutokset. Aikavälin (alkupvm...loppupvm) maksimipituus on 31 päivää. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/muutostiedot
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/muutostiedot?limit=5&page=2
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"],
"ytunnukset": ["1234567-8", "2345678-9"],
"alkupvm": "2020-01-01",
"loppupvm": "2020-01-30"
}
Koodistot
Rakenteessa esitetään koodistojen nimet ja koodiarvot.
Hakuparametrit
Ei hakuparametreja.
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/koodistot
Tiedotteet
Rakenteessa esitetään palvelun käyttöön liittyvät voimassa olevat tiedotteet, kuten tiedot tulossa olevista käyttökatkoista tai uusien käyttöehtojen julkaisemisesta.
Hakuparametrit
Ei hakuparametreja.
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/tiedotteet
Valtuutusavaimet
Rakenteessa esitetään tiedot kysyttyjen valtuutusavainten voimassaolosta ja niihin liittyvien käyttöehtojen hyväksymisestä.
Hakuparametrit
| Nimi | Arvot | Lkm | Kuvaus |
| valtuutusavaimet | valtuutusavain | 1..n | Yhtiön tietoihin oikeuttava valtuutusavain, jonka saa haettua Osakeluettelon siirtopalvelusta. |
Esimerkit
https://htjws.nls.fi/htj/v1/kysely/isannoitsijat/valtuutusavaimet
POST:
{
"valtuutusavaimet": ["HTJ-2020-08-10-6f485da4-6ab8-49ef-9216-ec79afb53cvd"]
}
Versiohallinta
Sovellusversio 15.4.2025
Muutokset
Osakeryhmän perustiedot
Tuotteelle lisätty seuraavat uudet tiedot:
- Osakkeen muoto
- Aikaisemmat osakeryhmät
..."aikaisemmatOsakeryhmat": [ { "osakeryhmatunnus": "OH4D47N49EL8KE43" }, { "osakeryhmatunnus": "OH4D47N49EL8KE42" }],..."osakkeenMuoto": { "koodisto": "OSAKEMUOTO", "koodi": "SM"},... |
Osakeryhmän perustiedot -tuotteelle merkattu seuraavat tiedot poistettaviksi tulevissa julkaisuversioissa. Ajankohta vahvistetaan erikseen.
- Sähköinen omistus true/false
- Voimaantulopäivämäärä Osakehuoneistorekisterissä
..."sahkoinenOmistusmerkinta": true,..."voimaantulopvmOsakehuoneistorekisterissa": "2019-07-08",... |
Osakeryhmien haku hakuehdoin (osakeryhmien suppeat tiedot)
Tuote palauttaa myös lakanneet osakeryhmät. Tuotteelle lisätty seuraavat uudet tiedot:
- Osakeryhmän rekisteröintipäivämäärä
- Osakelukumäärä
- Osakkeen muoto
- Osakeryhmän lakkaamispäivämäärä
..."rekisterointipvm": "2019-08-23",..."osakelukumaara": 200,..."osakkeenMuoto": { "koodisto": "OSAKEMUOTO", "koodi": "OK"},..."lakkaamispvm": "2019-09-23",... |
Osakeryhmien haku hakuehdoin-tuotteelle merkattu seuraavat tiedot poistettaviksi tulevissa julkaisuversioissa. Ajankohta vahvistetaan erikseen.
- Sähköinen omistusmerkintä true/false
..."sahkoinenOmistusmerkinta": true,... |
Sovellusversio 12.3.2025
Muutokset
Osakeryhmän omistukset-tuotteelle lisätty uusi perustelaji koodiarvolla 8 "Aikaisempi omistus, yhtiöjärjestyksen muutos".
"koodisto": "PERUSTELAJI",
"koodi": "8",
"seliteFi": "Aikaisempi omistus, yhtiöjärjestyksen muutos",
"seliteSv": "Tidigare ägande, ändring av bolagsordning",
"voimassaoloAlkaa": "20.01.2025"
Sovellusversio 5.2.2025
Muutokset
Osakeryhmän rajoitukset-tuotteen "vapaaehtoinen selite" maksimi merkkimäärä nostettu 4000 merkkiin. Muutos koskee kaikkia rajoituslajeja.
},
"vapaaehtoinenSelite": {
"type": "string",
"maxLength": 4000,
"description": "Rajoitukseen liittyvä selite."
},
Sovellusversio 14.1.2025
Muutokset
Osakeryhmistä annettavaa tietopalvelua laajennettu:
Tietopalvelua on laajennettu myös uusiin Kaupparekisterissä rekisteröityihin osakeryhmiin yhtiöissä, joissa on tehty yhtiöjärjestyksen muutos. Tällaisesta osakeryhmästä saa tietopalvelua heti sen rekisteröinnistä alkaen.
Kaikista tuotteista voidaan pyytää tiedot huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä.
- Uuden kaupparekisterissä rekisteröidyn osakeryhmän tila on huoneistotietojärjestelmässä "Syntyvä", kunnes osakeryhmän tiedot on tarkistettu ja mahdolliset rekisteröinnit on kohdistettu tai haettu. Tällaisen osakeryhmän tiedot eivät ole vielä ajan tasalla.
- Osakeryhmän tila on "Voimassa", kun osakeryhmän tiedot on tarkistettu ja rekisteröinnit kohdistettu huoneistotietojärjestelmässä.
- Osakeryhmän tila on "Lakkaava", jos se on lakannut kaupparekisterissä, mutta sillä on rekisteröintejä, joita täytyy mahdollisesti kohdistaa uusille osakeryhmille.
Muutokset osakeryhmän tilaa palauttaviin tuotteisiin
Osakeryhmän haku hakuehdoin ja Osakeryhmän perustiedot Osakeryhman_tila koodisto palauttaa nyt myös osakeryhmän tilan koodiarvoa 3 (syntyvä)
"olotila": {
"koodisto": "OSAKERYHMAN_TILA",
"koodi": "3"
Aikaisemmin tiedot palautettiin vain, kun osakeryhmän tila on "voimassa" (koodiarvo 1) ja "lakkaava" (koodiarvo 4).
Osakeryhmän muutostiedot-tuotteen ”Yhtiön muutostyyppi” koodistoon lisätty uusi koodiarvo 12 ”Osakkeen muodon muuttaminen”.
"koodisto": "YHTION_MUUTOSTYYPPI",
"koodi": "12",
"seliteFi": "Osakkeen muodon muuttaminen",
"seliteSv": "Ändring av aktieform",
"voimassaoloAlkaa": "14.01.2025"
Uusi muutostyyppi syntyy, kun yhtiöjärjestyksen muutoksessa syntyneen uuden osakeryhmän osakkeen muoto vahvistetaan sähköiseksi merkinnäksi tai osakekirjaksi. Osakkeen muoto ei ole aina tiedossa heti yhtiöjärjestyksen muutoksen jälkeen, jolloin se vahvistetaan Maanmittauslaitoksessa.
Muutos Osakeryhmän perustiedot ja Osakeryhmien haku hakuehdoin -tuotteissa:
Osakeryhmän tietona näytettävään sahkoinenOmistusmerkinta false-arvon palauttamiseen on tehty muutos. False-arvo palautetaan myös kun osakkeen muotoa ei ole vielä vahvistettu. SahkoinenOmistusmerkinta tietoa näytetään rajapinnoissa: Osakeryhmän perustiedot, Osakeryhmien haku hakuehdoin.
- sahkoinenOmistusmerkinta arvo "false" palautetaan, kun osakkeen muoto on osakekirja tai sitä ei ole vielä vahvistettu.
- sahkoinenOmistusmerkinta arvo "true" palautetaan, kun osakkeen muoto on sähköinen merkintä.
Osakeryhman_huomio koodistoa on päivitetty
Osakeryhman_huomio-koodiston koodiarvoa 3 on päivitetty. Koodiarvo 3 palautetaan osakeryhmille, joiden tila on lakkaava (koodiarvo 4):
- "koodisto": "OSAKERYHMAN_HUOMIO",
"koodi": "3",
"seliteFi": "Osakeryhmä on lakannut yhtiöjärjestyksen muutoksessa. Tiedot eivät ole huoneistotietojärjestelmässä ajan tasalla.",
"seliteSv": "Aktiegruppen har upphört vid en ändring av bolagsordningen. Uppgifterna i bostadsdatasystemet är inte uppdaterade..",
"voimassaoloAlkaa": "14.01.2025"
Osakeryhman_huomio-koodistoon on lisätty uusi koodiarvo 7. Koodiarvo 7 palautetaan osakeryhmille, joiden tila on syntyvä (koodiarvo 3):
- "koodisto": "OSAKERYHMAN_HUOMIO",
"koodi": "7",
"seliteFi": "Osakeryhmä on syntynyt yhtiöjärjestyksen muutoksessa. Tiedot eivät ole huoneistotietojärjestelmässä ajan tasalla.",
"seliteSv": "Aktiegruppen har uppstått vid en ändring av bolagsordningen. Uppgifterna i bostadsdatasystemet är inte uppdaterade.",
"voimassaoloAlkaa": "14.01.2025"
Muutokset rajoituslaji-koodistoon
Rajoituslaji-koodistoon lisätty uusi rajoituslaji koodiarvo 41 "Tieto osakeluetteloon merkitystä omistajasta ja mitätöimättömästä osakekirjasta" :
- "koodisto": "RAJOITUSLAJI",
"koodi": "41",
"seliteFi": "Tieto osakeluetteloon merkitystä omistajasta ja mitätöimättömästä osakekirjasta",
"seliteSv": "Uppgift om ägare som antecknats i aktieboken och om icke makulerat aktiebrev",
"voimassaoloAlkaa": "14.01.2025"
Sovellusversio 7.11.2024
Muutokset
- Tietopalvelukoodiston saantolaji-koodistoon aktivoitu saantolajit
- "koodi": "4","seliteFi": "Perintö","seliteSv": "Arv","voimassaoloAlkaa": "01.01.2000"
- "koodi": "5","seliteFi": "Testamentti","seliteSv": "Testamente","voimassaoloAlkaa": "01.01.2000"
- "koodi": "13","seliteFi": "Perinnönjako","seliteSv": "Arvskifte","voimassaoloAlkaa": "01.01.2000"
- "koodi": "15","seliteFi": "Ositus ja perinnönjako","seliteSv": "Avvittring och arvskifte","voimassaoloAlkaa": "01.01.2000"
- "koodi": "31","seliteFi": "Jakautuminen","seliteSv": "Delning","voimassaoloAlkaa": "01.01.2000"
Sovellusversio 2.10.2024
Muutokset
- Osakeryhmän muutostiedot-tuotteen ”Yhtiön muutostyyppi” koodistoon lisätty uusi koodiarvo 11 ”Omistusoikeuden rekisteröinti, ei omistajavaihdosta”.
"koodisto": "YHTION_MUUTOSTYYPPI",
"koodi": "11",
"seliteFi": "Omistusoikeuden rekisteröinti, ei omistajanvaihdosta",
"seliteSv": "Registrering av äganderätt, inget ägarbyte",
"voimassaoloAlkaa": "01.07.2024"
Uusi muutostyyppi syntyy, kun omistuksen rekisteröinnissä tehdään hyväksytty lainvoimainen ratkaisu kohteelle, jossa omistus ei ole vaihtunut. Koskee omistuksen rekisteröintejä perustekirjauksella: osakekirja, hallituksen selvitys, väliaikaistodistus tai yhtiön ilmoitus
Sovellusversio 19.6.2024
Muutokset
- Rajoituslajikoodistosta lakkautettu rajoituslajit koodiarvo 2 "Muuta rajoitusta koskeva riita" ja koodiarvo 33 "Asunto-osakkeen saantoon kohdistuu yhtiöjärjestyksen mukainen muu vaihdannanrajoitus"
"koodisto": "RAJOITUSLAJI",
"koodi": "2",
"seliteFi": "Muuta rajoitusta koskeva riita",
"seliteSv": "Tvist om en annan begränsning",
"voimassaoloAlkaa": "01.01.2000",
"voimassaoloPaattyy": "01.05.2024"
"koodisto": "RAJOITUSLAJI",
"koodi": "33",
"seliteFi": "Asunto-osakkeen saantoon kohdistuu yhtiöjärjestyksen mukainen muu vaihdannanrajoitus",
"seliteSv": "Förvärv av bostadsaktie omfattas av en annan begränsning av omsättning i enlighet med bolagsordningen",
"voimassaoloAlkaa": "01.01.2000",
"voimassaoloPaattyy": "01.05.2024"
Sovellusversio 7.2.2024
Muutokset
- Osakeryhmän huomiot koodistosta lakkautettu koodiarvo 1
"koodisto": "OSAKERYHMAN_HUOMIO",
"koodi": "1",
"seliteFi": "Turvakielto tai yhteystietojen luovutuskielto",
"seliteSv": "Spärrmarkering el. förbud mot utlämning av kontaktuppgifter",
"voimassaoloAlkaa": "01.01.2023",
"voimassaoloPaattyy": "09.01.2024"
- Yhdenkään osakeryhmään liittyvän henkilön luovutuskielto ei enää jatkossa piilota osakeryhmiltä henkilötietoja. Tietojen luovutuskiellossa olevasta henkilöstä palautetaan jatkossa kaikki samat tiedot kuin "ei tietojen luovutuskiellossa" olevasta henkilöstä, osoitetietoja lukuun ottamatta. Osoitteen osalta kyselyissä palautetaan tietojen luovutuskiellossa olevasta henkilöstä vain Maanmittauslaitoksella tallennettu osakkeen omistajan taloyhtiötä varten ilmoittama maa postiosoite ja/tai sähköposti.
Virheiden hallinta
Palveluun kytkeytymiseen tai saatavuuteen sekä tietoliikenteeseen liittyvistä virhetilanteista palautetaan asiakassovellukselle virheilmoitus HTTP-virhekoodeina. Palvelu palauttaa seuraavia virhekoodeja:
| Virhekoodi | HTTP-tunnus | Selitys |
| 400 | Bad Request | Hakupyyntö tai sen parametrit ovat virheellisiä. |
| 401 | Unauthorized | Palvelu ei hyväksy asiakassovelluksen välittämää käyttäjätunnistetta. |
| 403 | Forbidden | Valtuutuskoodi ei valtuuta kyseiseen yhtiöön. |
| 404 | Not found | Parametreilla ei löydy tietoa. Esimerkiksi tilanne, jossa yhtiön osakeluetteloa ei ole vielä siirretty huoneistotietojärjestelmään. |
| 500 | Internal Server Error | Pyyntöä käsiteltäessä tapahtunut jokin odottamaton virhetilanne. |
Koekäyttöympäristö
Aineisto
Koekäyttöympäristöön on luotu kuvitteellisten yhtiöiden perustietoja kutakin isännöintijärjestelmää varten. Isännöintijärjestelmistä tuodaan yhtiöille kohdetiedot sekä osakeluettelotiedot. Ennen osakeluettelon siirron hyväksymistä niistä ei pysty hakemaan tietopalvelukyselyillä tietoja. Mikäli isännöintijärjestelmien omien yhtiöiden tiedoilla halutaan testata tietopalveluhakuja, pitää yhtiön osakeluettelon siirto hyväksyä ja sen jälkeen tietopalveluja voidaan testata. Jos tämän jälkeen halutaan taas testata osakeluettelon siirtoa, pitää pyytää oman yhtiön palauttamista osakeluettelon siirtoa edeltäneeseen tilanteeseen.
Tietopalvelukyselyiden testaamista varten koekäyttöympäristössä on kolme yhteistä yhtiötä:
- y-tunnus 6583621-2
- y-tunnus 3058343-8
- y-tunnus 6306462-6
Testitapaukset (päivitetty 16.4.2025)
Käyttöönotto
Verkkopalveluiden asiakastuesta voi pyytää sähköpostitse (verkkopalvelut(at)maanmittauslaitos.fi) oikeutta koekäyttöympäristöön. Viestistä tulisi käydä ilmi, minkälaista palvelua ollaan suunnittelemassa ja miten palvelusta saatuja tietoja on tarkoitus hyödyntää mahdollisessa tuotantokäytössä.
Koekäyttöympäristön käyttöön myönnetään lupa, joka on voimassa kuusi kuukautta.
Tuotteet
Kaikki palvelun tuotteet ovat koekäytettävissä. Tuotantopalvelussa olevasta tuotteen kyselyosoitteesta saa koekäyttöpalvelun osoitteen vaihtamalla osoitteen alkuun htjws.nls.fi -> htjwskoe.nls.fi.
Esimerkiksi osakeryhmän perustiedot:
https://htjwskoe.nls.fi/htj/v1/kysely/isannoitsijat/osakeryhmat/perustiedot