VTJ-muutosrajapinta

VTJ-muutosrajapinnan avulla julkishallinnon organisaatiot päivittävät omaan henkilörekisteriinsä väestötiedoissa tapahtuneet muutokset – esimerkiksi muutot, syntymät, kuolemat ja nimenmuutokset. Esimerkiksi kunnat toimivat rekisterin pitäjinä.

Väestötiedot muuttuvat jatkuvasti: pelkästään muuttoja tehdään Suomessa lähes miljoona vuodessa eli keskimäärin noin 2 500–3 000 joka päivä. Ilman säännöllistä päivitystä organisaation rekisterin tiedot vanhenevat siis nopeasti.

Rajapinta on tarkoitettu rekisterin tietojen ylläpitoon. Yksittäisten henkilötietojen hakuun käytetään VTJkysely-rajapintaa.

Vanha Muutostietopalvelu poistuu käytöstä 31.12.2026

Nykyisten Muutostietopalvelun käyttäjien on siirryttävä VTJ-muutosrajapintaan ennen määräaikaa. Aloita siirtyminen hyvissä ajoin, sillä tietoluvan käsittely, tekninen toteutus ja testaus vievät aikaa.

Näin siirryt VTJ-muutosrajapintaan

Siirtyminen etenee viidessä vaiheessa:

  1. Valitse käyttötarkoitukseen sopiva tuote
  2. Hae tietolupa
  3. Valitse tietojen välitystapa ja päivitysrytmi
  4. Toteuta ja testaa tekniset muutokset
  5. Irtisano vanha Muutostietopalvelu

Mikä muuttuu?

VTJ-muutosrajapinta on ajantasaisempi ja teknisesti uudempi kuin vanha Muutostietopalvelu.

Muutostietopalvelun ja VTJ-muutosrajapinnan vertailu
Ominaisuus Muutostietopalvelu VTJ-muutosrajapinta
Käyttöönottovuosi 1999 2019
Tekninen toteutus Tiedostosiirto Ohjelmointirajapinta (API)
Merkistö ISO 8859-1 UTF-8
Päivitysrytmi 1–2 viikkoa 1–24 tuntia
Aineistomuoto Peräkkäistiedosto JSON (standardi)
Ulkokuntalaisten tiedot Ei mahdollista Mahdollista
Tietosisällön muutokset Työläitä: kiinteä tiedostomääritys, eikä palveluun tehdä enää muutoksia. Joustavia: tietosisältö valitaan tuotteittain, ja tuotteita ja poimintaehtoja kehitetään tarpeen mukaan.

Kun organisaatio siirtyy Muutostietopalvelusta VTJ-muutosrajapintaan, aineistoformaatti ja tietojen välitystapa muuttuvat. Tämä vaatii muutoksia myös tekniseen toteutukseen, jolla organisaation rekisteri päivitetään. Palvelun aloituksen yhteydessä rekisteriin välitetään sovitut perustiedot kaikista rekisterin henkilöistä.

1. Tuotteet ja tietosisällöt

Ennen tietoluvan hakemista organisaation on valittava käyttötarkoitukseensa sopiva tuote. Digi- ja väestötietovirasto (DVV) luovuttaa vain tiedot, jotka ovat lakisääteisesti perusteltuja ja välttämättömiä.

Kuntarajaustuotteet

Kuntarajaustuotteet soveltuvat kunnan oman väestörekisterin tai hyvinvointialueen toimialueen kuntien asukkaiden tietojen päivitykseen. Päivitys tapahtuu henkilöiden kotikunnan perusteella.

Henkilötunnuksella rajattavat tuotteet

Henkilötunnuksella rajattavilla tuotteilla voi päivittää esimerkiksi asiakas-, palvelu-, opetus- tai laskutusrekisteriä. Päivitys kohdistuu vain niihin henkilöihin, jotka ovat jo luvansaajan rekisterissä. Luvansaaja ylläpitää itse henkilötunnuslistaa, jonka perusteella rekisteriä päivitetään. Näin kunta voi päivittää myös ulkokuntalaisten henkilöiden tietoja lakisääteisiä tehtäviään varten.

Räätälöidyt tuotteet

Viranomaisille ja viranomaistehtäviä hoitaville toimijoille voidaan tarvittaessa räätälöidä omia poimintaehtoja, joilla henkilöiden tietoja päivitetään.

Apua tuotteen valintaan

Katso kuvaus siitä, miten VTJ-muutosrajapinnan tuotteet soveltuvat kunnan päivitystarpeisiin.

2. Tietolupa ja vinkit hakemiseen

Palvelun käyttö edellyttää tietolupaa. Hae tietolupaa Digi- ja väestötietoviraston verkkoasioinnissa.

Kunnille, kuntayhtymille ja hyvinvointialueille on myönnetty viranomaistehtävien hoitoa varten yleiset tietoluvat eli niin kutsutut kattoluvat. Kattolupa valitaan verkkoasioinnissa. Tutustu kattolupiin:

Perehdy hakemusohjeisiin ennen tietolupahakemuksen täyttämistä:

Hakemuksen käsittelyaika riippuu muun muassa luovutettavista tiedoista. Palvelun käyttöönottoaikataulusta sovitaan erikseen asiakkaan kanssa.

Vinkkejä hakemuksen valmisteluun

  • Älä tee yksin. Ota valmisteluun mukaan tietojen omistajat, tietosuoja- ja lakiasiantuntijat sekä ICT-toimittaja.
  • Kartoita tarpeet. Määrittele lakisääteinen tehtävä, johon tietoja käytetään, ja valitse sen perusteella oikea tuote.
  • Hyödynnä tuki. Tutustu DVV:n hakemusohjeisiin tai varaa tarvittaessa paikka tietolupaklinikalta. 

3. Tietojen välitystavan valinta

Asiakas voi valita tekniseen ympäristöönsä parhaiten sopivan välitystavan.

Vaihtoehto 1: Suomi.fi-palveluväylä

Tiedot välitetään Suomi.fi-palveluväylän kautta. Suomi.fi Kehittäjille -sivusto sisältää ohjeet palveluväylän käyttöönoton hallinnollisista ja teknisistä toimenpiteistä.

Välitoimijamallin avulla IT-toimittaja tai muu palveluntarjoaja voi täyttää palveluväylän käyttölupahakemuksen asiakasorganisaation, esimerkiksi kunnan tai hyvinvointialueen, puolesta ja lähettää sen tälle hyväksyttäväksi.

Vaihtoehto 2: Suoraliittymä

Yhteys muodostetaan suoraan DVV:n rajapintaan. Tunnistaminen ja suojaus perustuvat seuraaviin tekijöihin:

  • DVV:n myöntämä asiakasvarmenne. Varmenteen nimikenttä (Common Name) ilmoitetaan osoitteeseen [email protected]. Asiakasvarmenne toimii organisaation järjestelmän sähköisenä henkilöllisyystodistuksena, jonka avulla lähettäjä ja vastaanottaja tunnistetaan ja niiden välinen tietoliikenneyhteys salataan.
  • Asiakkaan IP-osoite, josta kutsut muodostetaan.
  • Tietoluvan perusteella myönnettävä käyttäjätunnus ja salasana.

VTJ-muutosrajapinnan tietoja voidaan välittää myös suoraliittymän kautta. Suoraliittymässä asiakas muodostaa yhteyden suoraan Digi- ja väestötietoviraston rajapintaan ilman Suomi.fi-palveluväylää.

Näin otat suoraliittymän käyttöön:

1. Hae DVV:n myöntämä asiakasvarmenne verkkoasioinnissa ja ilmoita sen nimikenttä eli Common Name DVV:lle osoitteeseen [email protected].

2. Ilmoita samassa sähköpostissa IP-osoite, josta VTJ-muutosrajapintaa kutsutaan.

3. Käyttäjätunnus ja salasana myönnetään hyväksytyn tietoluvan perusteella. Samalla käyttöoikeudet rajataan vain niihin tietoihin, jotka ovat asiakkaan lakisääteisten tehtävien hoitamiseksi tarpeellisia.

Huom! Asiakas on vastuussa siitä, että varmenne on voimassa.

4. Testausympäristö nimeltä hiekkalaatikko

VTJ-muutosrajapintaa voi testata ja kehittää vapaasti testiympäristössä nimeltä hiekkalaatikko.

Hiekkalaatikon tiedot eivät sisällä oikeita henkilötietoja, vaan henkilötunnukset ja muut henkilötiedot ovat testiaineistoja. Testiympäristön käyttäjätunnus ja salasana ovat saatavilla hiekkalaatikko-sivustolta. Tunnukset ovat kaikille testaajille samat, joten erillisiä tunnuksia ei tarvitse hakea.

Vaihtoehto 1. Testaus avoimen rajapinnan kautta

Testi-hiekkalaatikon käyttö on mahdollista avoimen rajapinnan kautta ilman rekisteröitymistä tai erillistä lupaa: hiekkalaatikko-sivusto. Voit siis testata sitä ilman Suomi.fi-palveluväylää.

Vaihtoehto 2. Testaus Suomi.fi-palveluväylän kautta

Halutessasi voit testata hiekkalaatikkoa myös Suomi.fi-palveluväylän kautta. Rajapinnan osoite on api.hiekkalaatikko.muutostietopalvelu.dvv.fi. Palveluväylän testiyhteyden käyttöönotto edellyttää, että

  • organisaatiolle on myönnetty palveluväylän käyttölupa
  • organisaatiolla on käytössään liityntäpalvelin, johon lisätään testi-alijärjestelmä
  • testi-alijärjestelmälle haetaan käyttölupa: täytetty alijärjestelmän käyttölupahakemus lähetetään osoitteeseen [email protected].

5. Vanhan Muutostietopalvelun irtisanominen

Kun VTJ-muutosrajapinta on tuotantokäytössä, irtisano vanha Muutostietopalvelu sähköpostitse lähettämällä siitä sähköposti osoitteeseen [email protected].

Hinnat

VTJ-muutosrajapinnan käyttöönottomaksu on 1 000 euroa per uusi yhteys.

  • Jos päivitettäväksi tulee useita rekistereitä eri yhteyksien kautta, käyttöönottomaksu veloitetaan jokaisesta uudesta yhteydestä.
  • Muutostietopalvelun asiakkaat saavat ilman käyttöönottomaksua yhtä monta VTJ-muutosrajapinta-yhteyttä kuin asiakkaalla on Muutostietopalvelun tilauksia.

Palvelun käyttö on käyttöönoton jälkeen maksutonta valtiovarainministeriön maksuasetuksen (793/2024) 2 §:ssä mainituille valtion ja kuntien viranomaisille.
Muilta asiakkailta veloitetaan tietoyksikköhinta, joka on 0,039 euroa per tietue.

Usein kysytyt kysymykset