Rajapinnan kautta voidaan siirtää hakeneiden, valittujen ja paikan vastaanottaneiden tietoja opintopolusta korkeakouluille ja Oili-palveluun (ilmoittautuminen korkeakouluun).
Testiympäristössä se löytyy osoitteesta: https://virkailija.testiopintopolku.fi/suoritusrekisteri/rest/v5/kkhakijat.
Tuotantoympäristössä se löytyy osoitteesta https://virkailija.opintopolku.fi/suoritusrekisteri/rest/v5/kkhakijat?hakukohde=1.2.246.562.20.37736286735 (vaatii autentikoinnin ja sopivat käyttöoikeudet). Se tukee rajausta oppijanumeron, hakukohteen tai hakukohderyhmän mukaan, alla esimerkki hakukohdekohtaisesta hausta (HY, ympäristötieteet, luonnontieteiden kandidaatti ja filosofian maisteri).
Automaattisesti päivittyvä swagger -dokumentaatio: https://virkailija.testiopintopolku.fi/suoritusrekisteri/swagger/index.html#!/kkhakijat_5/haeKkHakijat
Kutsuparametrit
Parametri | Kuvaus |
|---|---|
| oppijanumero | Valtakunnallinen oppijanumero. Rajaa tuloksen yksittäisen hakijan tietoihin. |
| organisaatio | Organisaation OID. Rajaa tuloksen tietyn korkeakoulun tietoihin. |
| haku | Haun OID. Rajaa tuloksen tietyn haun tietohin. |
| hakukohde | Hakukohteen OID. Rajaa tuloksen tietyn hakukohteen tietohin. |
| hakukohderyhmä | Hakukohderyhmän OID. Rajaa tuloksen tietyn hakukohderyhmän tietoihin |
| filter | Vain valitut/Vain vastaanottaneet/Kaikki hakijat |
| palautaKoulusivistyskielet | Kun true, tieto koulusivistyskielistä palautetaan vastauksessa. Tieto palautetaan vain paikan vastaanottaneille suorituskykysyistä. |
Vastausviestin tietojen kuvaukset
Uudet version 5 kentät merkitty vihreällä.
HUOM! Vastauksissa voi rajauksesta riippuen tulla myös vanhan muotoisia (haku-app) hakemuksia, jotka eivät sisällä kaikkia allaolevia pakolliseksi merkittyjä tietoja. Tuoreissa ei-synteettisissä hakemuksissa pakolliseksi merkityt tiedot löytyvät aina, mutta varaudu tiedon hyödyntäjänä tarkistamaan kenttien olemassaolo ennen käyttöä.
| Tieto | JSON-elementti | Pakollinen | Peruste pakollisuudelle, ym. perusteet | Luokitus /standardi /suositus /koodisto /arvoalue |
|---|---|---|---|---|
| Henkilötunnus | hetu | X | Suomalaisilta hetu, muilta seitsemänmerkkinen tieto. | Henkilötunnus tai syntymäaika 7-numeroisessa muodossa; henkilötunnus pakollinen jos kansalaisuus suomi; henkilötunnuksen tarkistusnumeron mukainen tarkistus. |
| Valtakunnallinen oppijanumero | oppijanumero | X | Kaikille pakollinen. OPH:n hallinnoima. Kaikilla ei ole hetua. | OPH:n hallinnoima, kansallinen, yksilöivä koodisto (OID-luokittelu JHS 159) |
| Sukunimi | sukunimi | X | Raportointi ym. hallinnolliset tarpeet. | Oppijan sukunimi. Nimen oikeellisuus on tarkastettu väestötietojärjestelmästä niiden oppijoiden osalta, joiden tiedot sieltä löytyvät. Oppijan, jonka tietoja ei löydy väestötietojärjestelmästä, nimitietoja ei ole Opetushallituksen toimesta varmennettu. |
| Etunimet | etunimet | X | Raportointi ym. hallinnolliset tarpeet. | Oppijan kaikki etunimet. Nimien oikeellisuus on tarkastettu väestötietojärjestelmästä niiden oppijoiden osalta, joiden tiedot sieltä löytyvät. Oppijan, jonka tietoja ei löydy väestötietojärjestelmästä, nimitietoja ei ole Opetushallituksen toimesta varmennettu. |
| Kutsumanimi | kutsumanimi | X | Raportointi ym. hallinnolliset tarpeet. | Oppijan kutsumanimi. Kutsumanimen on oltava yksi etunimet-kentän etunimistä. |
| Lähiosoite | lahiosoite | X | Yhteydenpito, hallinnolliset tarpeet | Oppijan lähiosoite. Osoite on hakijan ilmoittama ja se on vapaamuotoinen. |
| Postinumero | postinumero | X | Yhteydenpito, hallinnolliset tarpeet | Oppijan postinumero. Jos hakijalla on osoite Suomessa, on postinumero Opintopolun posti-koodiston mukainen. Ulkomaiset postinumerot ovat vapaamuotoisia eikä niiden oikeellisuutta ole tarkistettu. Tieto on hakijan ilmoittama. |
| Postitoimipaikka | postitoimipaikka | X | Yhteydenpito, hallinnolliset tarpeet | Oppijan postitoimipaikka. Jos hakijalla on osoite Suomessa, haetaan postitoimipaikka Opintopolun posti-koodistosta postinumeron perusteella. Ulkomaiset postitoimipaikat ovat vapaamuotoisia. Jos haku on tehty toisessa järjestelmässä, saattaa postitoimipaikka puuttua. Samoin postitoimipaikka saattaa puuttua ulkomaiselta hakijalta. |
| Osoitteen maa | maa | X | Yhteydenpito, hallinnolliset tarpeet | ISO-3166-1, lisäksi 999=Tuntematon. Asuinmaatieto on peräisin hakijalta. |
| Kansalaisuudet | kansalaisuudet | X | Raportointi. Hallinnolliset tarpeet, ohjaus yms. | ISO-3166-1, lisäksi 999=Tuntematon. Sisältää kaikki hakijan kansalaisuudet listana. |
| Syntymäaika | syntymaaika | Esim. 01.01.2001. | ||
| Matkapuhelinnumero | matkapuhelin | Oppijan ilmoittama matkapuhelinnumero. Tieto on vapaamuotoinen. Kansainvälisen puhelinnumeron merkitsemistapa perustuu Kansainvälisen televiestintäliiton (ITU) telestandardointisektorin suositukseen E.123. | ||
| Puhelinnumero | puhelin | Oppijan ilmoittama muu puhelinnumero (esim. lankapuhelin). Tieto on vapaamuotoinen. Kansainvälisen puhelinnumeron merkitsemistapa perustuu Kansainvälisen televiestintäliiton (ITU) telestandardointisektorin suositukseen E.123. | ||
| Sähköpostiosoite | sahkoposti | RFC 2822. Tieto on hakijan ilmoittama. | ||
| Kotikunta | kotikunta | X | Raportointi, opiskelijaterveydenhuolto yms. | Oppijan kotikunta, eli kunta jossa hakija on kirjoilla. Kotikunta ei välttämättä ole sama kuin asuinkunta. Kuntatieto ilmoitetaan kolminumeroisella koodilla, joka on Opintopolun kuntakoodiston mukainen. Jos oppijan asuinmaa on Suomi, ilmoitetaan attribuutissa suomalainen kotikunta. Ulkomailla asuvan oppijan kotikuntatieto on 200 = Ulkomaa |
| Sukupuoli | sukupuoli | X | Raportointi ym. hallinnolliset tarpeet. | 1 Mies, 2 Nainen. Henkilöllä oltava sukupuoli |
| Äidinkieli | aidinkieli | X | Raportointi ym. hallinnolliset tarpeet. | ISO-639-(1)2, VRK (vain kaksimerkkinen tunnus, esim "FI") Äidinkielitieto vahvistetaan väestötietojärjestelmästä niiden osalta, joilla on suomalainen henkilötunnus. |
| Asiointikieli | asiointikieli | X | Asiointi ym. hallinnolliset tarpeet. | Oppijan valitsema asiointikieli. Tieto on peräisin hakijalta. Asiointikieli ei välttämättä ole luotettava tieto erillishauissa hakeneiden oppijoiden osalta. Oletusarvo 9. Selitteet: 1 = suomi, 2 = ruotsi, 3= englanti, 9 = muu. |
| Koulusivistyskielet | koulusivistyskielet | X | Tutkintotodistusta varten. Tosien kotimaisen kielen, opinnäytetyön kielen, virkamiestutkinnon kielen määrittely. | Korvaa aiempien rajapintaversioiden koulusivistyskieli-kentän. Koulusivistyskieli/kielet ovat peräisin KOSKI-rekisteristä. Näitä voi olla 1-N, jos hakija on suorittanut eri kielillä esimerkiksi perusopetuksen ja lukion. Henkilön pitää olla suorittanut peruskoulu tai lukio vuonna 2018 tai sen jälkeen, jotta tieto voidaan Koskesta välittää. Selitteet: FI = suomi, SV = ruotsi, EN = englanti, 99 = muu. SE = Saame ,DE=Saksa Arvo on array '["FI","SV"] ja se on haettu ainoastaan paikan vastaanottaneille. Jos tietoa ei ole haettu tai löydy, palautuu tyhjä taulukko []. |
| Koulutusmarkkinointilupa | koulutusmarkkinointilupa | Boolean = true, false | ||
| Onko hakija ylioppilas? | onYlioppilas | X | Kertoo onko oppija suorittanut suomalaisen ylioppilastutkinnon. Tieto on peräisin Ylioppilastutkintolautakunnalta. Selitteet: true = oppija on suorittanut suomalaisen ylioppilastutkinnon false = oppija ei ole suorittanut ylioppilastutkintoa | |
| Onko hakija ensikertalainen? | ensikertalainen | X | Kertoo onko oppija tässä asiayhteydessä ensikertalainen. true = oppija on ensikertalainen | |
| Ylioppilastutkinnon suoritusvuosi | yoSuoritusVuosi | Esim. 1995 | ||
| Turvakielto | turvakielto | X | Jos henkilöllä on turvakielto, ei hänen kotikunta- tai osoitetietojaan saa antaa väestötietojärjestelmästä muille kuin viranomaisille. Turvakiellosta päättää maistraatti. Selitteet: true = henkilöllä on turvakielto false = henkilöllä ei turvakieltoa (oletusarvo) | |
| Hakemukset: | hakemukset | X | Voi esiintyä oppijan tiedoissa useaan kertaan, jos oppija on hakenut useissa eri hauissa. | |
| Haku | haku | X | ||
| Haun vuosi | hakuVuosi | X | ||
| Haun kausi | hakuKausi | X | Hakukausi. K=kevät, S=syksy. Perustuu Opintopolun kausikoodistoon. | |
| Hakemusnumero | hakemusnumero | X | Hakemuksen OID-tunnus. | |
| Hakemuksen jättämisen aikaleima | hakemusJattoAikaleima | X | ||
| Hakemuksen viimeinen muokkaus -aikaleima | hakemusViimeinenMuokkausAikaleima | X | ||
| Valinnan aikaleima | valinnanAikaleima | Hetki jolloin valinnan tulos on ollut ensimmäisen kerran hyväksytty ja julkaistu | ||
| Organisaation OID | organisaatio | X | Sen organisaation OID-tunnus, johon hakija on hakenut. OPH:n hallinnoima, kansallinen, yksilöivä koodisto (oID-luokittelu JHS 159) | |
| Hakukohteen OID | hakukohde | X | Pitää tietää, mihin opiskeluoikeus liittyy. | Sen hakukohteen OID-tunnus, johon oppija on hakenut. Voi esiintyä useita kertoja jos oppija on hakenut useaan hakukohteeseen. |
Hakutoiveen prioriteetti | hakutoivePrioriteetti | Numero: 1...n. Jos numero puuttuu ei haussa ole hakutoiveiden priorisointia | ||
| Hakukohteen korkeakoulu- ID-tunnus | hakukohdeKkId | Korkeakoulun hakukohteelle määrittämä tunniste. Tieto on vapaamuotoinen. Voi esiintyä useita kertoja jos oppija on hakenut useaan hakukohteeseen. | ||
| Valinnan tila | valinnanTila | KESKEN = ei valintatietoa | ||
| Valintatapajonon tyyppi | valintatapajononTyyppi | Tiedossa vain hyväksytyille hakijoille. Kenttä sisältää sen jonon tyypin, josta hakija on tullut valituksi. Tällä hetkellä mahdolliset arvot ovat "Avoin väylä", "Kilpailumenestys", "Koepisteet", "Todistusvalinta", "Yhteispisteet", "Muu". Ne vastaavat koodiston "valintatapajono" arvoja: https://virkailija.testiopintopolku.fi/koodisto-app/koodisto/view/valintatapajono/1 | ||
| Valintatapajonon nimi | valintatapajononNimi | Tiedossa vain hyväksytyille hakijoille. Merkitsevän valintatapajonon nimi (sen, josta hakija on esimerkiksi tullut valituksi) | ||
| Valintatapajonon pisteet | pisteet | Merkitsevän valintatapajonon pisteet | ||
Hyväksymisen ehto | hyvaksymisenEhto | Tieto siitä, onko hyväksyntä ehdollinen. Rakenne sisältää alikentät:
| ||
| Paikan vastaanottotieto | vastaanottotieto | X | Tieto siitä, onko henkilö ottanut paikan vastaan Opintopolussa. | KESKEN = ei vastaanottotietoa |
| Ilmoittautumistieto | ilmoittautumiset | Ei tehty; Läsnä (koko lukuvuosi); Poissa (koko lukuvuosi); Ei ilmoittautunut, Läsnä syksy, poissa kevät; Poissa syksy, läsnä kevät; Läsnä, keväällä alkava koulutus; Poissa, keväällä alkava koulutus tilat (1 = läsnä; 2 = poissa; 3 = poissa, ei kuluta opintoaikaa; 4 = puuttuu) | ||
| Pohjakoulutus | pohjakoulutus | X | Opetuksen suunnitteluun, hallinnollisia tarpeita varten. | Muuttunut koodisto: kentässä käytetään tässä rajapintaversiossa tarkempaa koodistoa pohjakoulutuskklomake vanhan koodiston sijaan. HUOM: näitä on 1-n taulukossa. |
| Hakukelpoisuus | hKelpoisuus | Kertoo onko hakija hakukelpoinen hakukohteeseen. Selitteet: ELIGIBLE = Hakukelpoinen (korkeakoulun määrittämä) AUTOMATICALLY_CHECKED_ELIGIBLE = Järjestelmän automaattisesti hyväksymä hakukelpoisuus INELIGIBLE = Ei hakukelpoinen NOT_CHECKED = Kelpoisuus tarkistamatta INADEQUATE = Puutteellinen | ||
| Hakukelpoisuuden tarkistamisen lähde | hKelpoisuusLahde | Lisätieto. Kertoo mikä on hakuelpoisuuden tarkistuksessa käytetty tietolähde. | Selitteet: UNKNOWN = Ei tiedossa COPY = Kopio REGISTER = Rekisteri AUTHENTICATED_COPY = Oikeaksi todistettu kopio OFFICIALLY_AUTHENTICATED_COPY = Virallinen oikeaksi todistettu kopio ORIGINAL_DIPLOMA = Alkuperäinen todistus LEARNING_PROVIDER = Oppilaitoksen toimittama tieto | |
| Hakijan maksuvelvollisuus | hKelpoisuusmaksuvelvollisuus | NOT_CHECKED = Ei merkitty | ||
| Hakukohteeseen liittyvät koulutukset: | hakukohteenkoulutukset | X | ||
| Hakukohteen koulutusmoduulin OID | komoOid | X | ||
| Tilastokeskuksen koulutuskoodi | tkKoulutuskoodi | X | ||
| Korkeakoulun oma koulutuksen id | kkKoulutusId | |||
Koulutuksen alkamiskausi | koulutuksenAlkamiskausi | https://virkailija.opintopolku.fi/koodisto-app/koodisto/view/kausi/1 | ||
Koulutuksen alkamisvuosi | koulutuksenAlkamisvuosi | Esim. 2023 | ||
Onko koulutus tutkintoon johtavaa? | johtaaTutkintoon | Boolean (true/false) | ||
| Liitteet: | liitteet | Hakemukseen liittyvät liittteet, voi olla yksi tai useita. | ||
| Haun OID-tunnus | hakuID | |||
| Liitteen hakuryhmän ID | hakuryhmaId | |||
| Liitteen tila | tila | |||
| Liitteen saapumisen tila | saapumisenTila | |||
| Liitteen nimi | nimi | Esim. RP-tutkintotodistuksen kopio | ||
| Liiteen vastaanottaja | vastaanottaja | Esim. Aalto-yliopiston hakijapalvelut | ||
| Lukuvuosimaksu | lukuvuosimaksu | MAKSETTU = Hakija on maksanut lukuvuosimaksun | ||
JSON-esimerkit
Esimerkki JSON-vastauksesta kun on haettu tietyn hakijan tiedot:
[{
"hetu":"010101A123N",
"oppijanumero":"1.2.246.562.24.82544081325",
"sukunimi":"Esimerkki",
"etunimet":"Rivi",
"kutsumanimi":"Rivi",
"lahiosoite":"wewee",
"postinumero":"00100",
"postitoimipaikka":"HELSINKI",
"maa":"246",
"kansalaisuudet":["246","703"],
"syntymaaika":"01.01.2001",
"matkapuhelin":"050 111 2222",
"puhelin":"050 3333 444",
"sahkoposti":"testi@example.com",
"kotikunta":"020",
"sukupuoli":"1",
"aidinkieli":"FI",
"asiointikieli":"1",
"koulusivistyskielet":["FI","SV"],
"koulutusmarkkinointilupa":true,
"onYlioppilas":true,
"ensikertalainen": true,
"yoSuoritusVuosi":"1995",
"turvakielto":false,
"hakemukset":[
{
"haku":"1.2.246.562.29.59856749474",
"hakuVuosi":2017,
"hakuKausi":"K",
"hakemusViimeinenMuokkausAikaleima": "2016-09-12T10:28:25",
"hakemusJattoAikaleima": "2016-08-31T08:19:45",
"hakemusnumero":"1.2.246.562.11.00000003298",
"organisaatio":"1.2.246.562.10.72985435253",
"hakukohde":"1.2.246.562.20.18496942519",
"hakutoivePrioriteetti": 2,
"hakukohdeKkId":"ENG10101",
"valintatapajononNimi": "Valintakurssi",
"pisteet": 20,
"hyvaksymisenEhto": {
ehdollisestiHyvaksyttavissa: true,
ehtoKoodi: "ttk",
ehtoFI: "Ehdollinen: tutkintotodistuskopio hakuperusteena olleesta tutkinnosta toimitettava määräaikaan mennessä",
ehtoSV: "Villkor: lämna in kopia av examensbetyget för den examen som du använt som ansökningsgrund inom utsatt",
ehtoEN: "Condition: Submit a copy of the qualification certificate of the qualification you used to prove your eligibility by the deadline"
},
"valinnanTila":"KESKEN",
"vastaanottotieto":"KESKEN",
"ilmoittautumiset":[
{
"kausi":"2017S",
"tila":4
},
{
"kausi":"2018K",
"tila":4
}
],
"pohjakoulutus":[
"pohjakoulutus_yo",
"pohjakoulutus_amp"
],
"hKelpoisuus":"NOT_CHECKED",
"hKelpoisuusLahde":"REGISTER",
"hKelpoisuusMaksuvelvollisuus":"NOT_CHECKED",
"hakukohteenKoulutukset":[
{
"komoOid":"1.2.246.562.13.27292937326",
"tkKoulutuskoodi":"751501",
"kkKoulutusId":"112301",
"koulutuksenAlkamiskausi": "K",
"koulutuksenAlkamisvuosi": 2017,
"johtaaTutkintoon": true
},
{
"komoOid":"1.2.246.562.13.27292937326",
"tkKoulutuskoodi":"655501",
"kkKoulutusId":"112301"
"koulutuksenAlkamiskausi": "S",
"koulutuksenAlkamisvuosi": 2017,
"johtaaTutkintoon": false
}
],
"liitteet":[
{
"hakuId":"1.2.246.562.20.18496942519",
"hakuRyhmaId":"",
"tila":"NOT_RECEIVED",
"saapumisenTila":"NOT_CHECKED",
"nimi":"Ammatillisen koulutuksen tutkintotodistuksen kopio",
"vastaanottaja":"Aalto-yliopiston hakijapalvelut"
},
{
"hakuId":"1.2.246.562.20.18496942519",
"hakuRyhmaId":"",
"tila":"NOT_RECEIVED",
"saapumisenTila":"NOT_CHECKED",
"nimi":"EB-, IB-, RP-tutkintotodistuksen kopio",
"vastaanottaja":"Aalto-yliopiston hakijapalvelut"
}
],
"lukuvuosimaksu": "MAKSETTU"
}
]
}
]