Tämä dokumentaatio tarkentaa Työmarkkinatorin työpaikkailmoitusten hallintarajapinnan teknisiä vaatimuksia ja kuvaa
varsinaisen rajapinnan käytön. Rajapinnan käyttöönoton prosessi on kuvattu tarkemmin
Työmarkkinatorin sivulla.
Samasta paikasta löytyvät myös työpaikkailmoitusten hallintaan liittyvän P66-rajapinnan OpenApi-kuvaukset.
Rajapinnan kautta ulkoisista palveluista voidaan julkaista työpaikkailmoituksia työmarkkinatorille. Työpaikkailmoituksen voi myös ajastaa julkaistavaksi. Julkaistuja ilmoituksia voi muokata ja arkistoida rajapinnan kautta.
Työpaikkojen halllintarajapinta on suunniteltu siten, että sen käyttäjän ei tarvitse olla työpaikan varsinainen työnantaja,
vaan sen kautta voidaan ilmoittaa useiden eri työn tarjoajien ilmoituksia. Työpaikkailmoitus luodaan rajapintakutsun
urlissa olevan businessId tiedon mukaiselle yritykselle.
Rajapinta työpaikkailmoitusten hallinnointiin Työmarkkinatorilla tarjotaan KEHA-keskuksen integraatioalustan (Kipa) kautta. Tunnukset integraatioalustan käyttöön sekä siihen liittyvät IP-avaukset tehdään KEHA-keskuksen toimesta osana rajapinnan käyttöönoton prosessia. Rajapinnan käytössä tarvittavat tunnukset toimitetaan rajapinnan käyttäjälle tietoturvallisesti. Tarkempia tietoja käyttöönotosta löytyy Työmarkkinatorin sivulla.
Tarkemmat työpaikkailmoitusten hallintaan liittyvät prosessit on kuvattu alla olevassa kaaviossa.
Varsinainen työpaikkailmoitusten hallinta tapahtuu Kipa-integraatioalustan palvelun P66 kautta
Työmarkkinatorin taustapalveluun. Tarjolla olevat rajapintakutsut, tietosisällöt ja vastaukset on kuvattu
halllintarajapinnan YAML-kuvauksessa.
Kutsut Kipa integraatioalustan kautta autorisoidaan API key mekanismilla ja kutsun header-tietoihin on lisättävä Kipan
käyttöä varten toimitettu KIPA-Subscription-Key. Header-attribuutti KIPA-MessageId asetetaan integraatioalustan toimesta
automaattisesti.
Kipa-integraatioalustan palvelu löytyy P66 löytyy seuraavista osoitteista
https://api-qa.ahtp.fi/kipa/p66/v1/jobpostinghttps://api.ahtp.fi/kipa/p66/v1/jobpostingTyöpaikkailmoitusta hallinnoidaan rajapinnan /v1/jobposting/{businessId}/{externalId}-kutsun kautta. Käytettävä
HTTP-protokollan metodi kertoo mitä ilmoitukselle ollaan tekemässä. Vaihtoehtoina ovat työpaikkailmoituksen tietojen
haku (GET), luonti tai päivittäminen (PUT) tai arkistointi (DELETE).
Työpaikkailmoituksen uniikki uuid-muotoinen externalId-tunniste tulee antaa rajapinnan kutsussa kun työpaikkailmoitusta
luodaan Työmarkkinatorille.
Jos olemassa olevaa työpaikkailmoitusta halutaan päivittää, kutsun header-tietoihin on lisättävä If-Match-tieto,
johon annetaan päivitettävän työpaikkailmoituksen tiedoissa olevan etag-kentän arvo.
Tällä varmistetaan se, että käsitellään työpaikkailmoituksen uusinta versiota. Jos etag-arvo ei vastaa tietokannan arvoa,
työpaikkailmoitusta on muokattu sen tietojen haun jälkeen ja päivitys ei onnistu. Päivityksen onnistumisen varmistamiseksi
kannattaa työpaikkailmoituksen tiedot hakea GET-metodilla ennen kuin päivitystä yritetään.
Työpaikkailmoitukset voi tuoda Työmarkkinatorille joko suoraan julkaistu tilassa tai odottamaan julkaisua tiettynä
ajankohtana. Julkaistua tai julkaisua odottavaa ilmoitusta voi päivittää. Ilmoitus poistuu julkaisusta hakuajan päätyttyä
automattisesti tai sen voi poistaa DELETE-metodilla. Molemmissa tapauksissa ilmoitus siirretään arkistoitu tilaan eikä
se ole enää julkinen.
Jos työpaikkailmoituksessa on asiatonta sisältöä ja viranomainen estää sen julkaisun, ilmoituksen tila muutetaan tilaan estetty ja sen jälkeen sitä ei voi enää käsitellä hallintarajapinnan kautta.
Työpaikkailmoituksen voi jättää kolmella kielellä ja käytetyt kielet tulee ilmoittaa languages-
attribuutin avulla. Sisällössä annetut lokalisoidut vapaatekstikentät validoidaan siten, että niissä on oltava
käännöselementit kaikilla annetuilla ilmoituksen kielillä. Jos näin ei ole, ilmoitus hylätään.
Työpaikkailmoituksissa käytetään ammattien ja osaamisten kuvaamiseen eurooppalaista ESCO-luokitusta. Luokituksesta on tehty kansallinen laajennus (FINESCO), joka sisältää uusimman ESCO-luokituksen ja siihen lisättyjä kansallisia ammatteja. FINESCOn käytöllä varmistetaan se, että työpaikkailmoitukset voidaan siirtää myös eurooppalaisen ammatillisen liikkuvuuden (EURES) portaaliin. FINESCO-luokitus on saatavilla Työmarkkinatorin sivuilta.
Ammattitiedon osalta on hyvä huomioida, että työpaikkojen tietoja tilastoidaan Työnvälitystilastoon. Sinne
voidaan välittää kuitenkin vain yksi ammatti, vaikka työpaikkailmoituksella sallitaan useamman ammatin
ilmoittaminen. Tästä syystä rajapinnan kautta tuotujen työpaikkailmoitusten tilastoinnissa käytettäväksi
ammatiksi otetaan ammatit listan 1. alkio, jos mainOccupation-kentässä ei ole arvoa.
Työpaikkailmiotuksessa vaaditut osaamiset ovat vapaaehtoinen tieto. Suositeltavaa olisi täyttää siihen työssä vaaditut osaamiset, koska niitä hyödynnetään työpaikkojen ja työnhakuprofiilien kohtaannossa.
Työpaikalle on annettava sijaintina vähintään yksi kunta, mutta muitakin sijainteja on mahdollista antaa. Kuntatieto vaaditaan, jotta työpaikkailmoitus ohjautuu oikealle työvoimaviranomaiselle.
Työpaikkailmoituksen tietomalli koostuu alla olevan kuvan mukaisista kokonaisuuksista. Pakolliset tiedot on indikoitu
lihavoidulla tekstillä. Puuttuvien tietojen osalta rakentessa tulee olla joko null tai avain jätetään kokonaan pois.
Alla on kuvattu esimerkki työpaikkailmoituksen rakenteesta luotaessa uutta työpaikkailmoitusta palveluun.
{
"languages": [
"fi",
"en"
],
"descriptionsContentType": "markdown",
"application": {
"expires": "2026-05-27T16:15:00.00Z",
"extraVisibility": [
"EURES_FLAGGED"
],
"helpText": {
"fi": "Cras tempor bibendum bibendum. Etiam auctor viverra augue at
posuere. Nunc fermentum aliquam est, vel eleifend ligula efficitur
nec. Ut nec ullamcorper lacus, nec aliquam justo. Quisque ultrices
enim diam, ac maximus lectus sodales in. Quisque quis maximus velit.
Phasellus a rutrum lorem. Ut mollis augue quis justo tempus
bibendum. Curabitur pretium ex neque, a pulvinar nulla scelerisque
quis.
\n\nAliquam elementum orci et vulputate consequat. Morbi sit amet
tortor sed ante volutpat congue. In egestas laoreet tempor. Aliquam
sed purus at tellus laoreet varius. Mauris eleifend nunc ante, a
tempor sem malesuada at. Nunc in nisl ligula. Donec porttitor
porttitor vulputate.",
"en": "Cras tempor bibendum bibendum. Etiam auctor viverra augue at
posuere. Nunc fermentum aliquam est, vel eleifend ligula efficitur
nec. Ut nec ullamcorper lacus, nec aliquam justo. Quisque ultrices
enim diam, ac maximus lectus sodales in. Quisque quis maximus velit.
Phasellus a rutrum lorem. Ut mollis augue quis justo tempus
bibendum. Curabitur pretium ex neque, a pulvinar nulla scelerisque
quis.
\n\nAliquam elementum orci et vulputate consequat. Morbi sit amet
tortor sed ante volutpat congue. In egestas laoreet tempor. Aliquam
sed purus at tellus laoreet varius. Mauris eleifend nunc ante, a
tempor sem malesuada at. Nunc in nisl ligula. Donec porttitor
porttitor vulputate."
},
"openPositions": 2,
"published": "2026-05-03T18:00:00Z",
"url": {
"fi": "https://example.com/lorem",
"en": "https://example.com/ipsum"
}
},
"client": {
"businessId": "2296962-1",
"company": "KEHA-keskus",
"companyVisible": true,
"industryCode": null,
"officeCode": null,
"officeName": null
},
"externalLinks": [
{
"description": "External link",
"url": "http://www.google.com/"
}
],
"location": {
"countries": [
"FI"
],
"municipalities": [
"090",
"097"
],
"regions": [
"01",
"14"
],
"requiresTravelling": true,
"workplaceAddress": "Valamontie 42",
"workplaceName": {
"fi": "Valamon luostari",
"en": "Valamon luostari"
},
"workplacePostOffice": "Uusi-Valamo",
"workplacePostalCode": "79850"
},
"owner": {
"company": {
"fi": "Eezy Henkilöstöpalvelut Oy",
"en": "Eezy Henkilöstöpalvelut Oy"
},
"industryCode": "78200",
"officeCode": null,
"officeName": null,
"reference": "reference 12345"
},
"position": {
"continuityOfWork": [
"01"
],
"criminalRecordVerification": [
"1"
],
"drivingLicenses": [
"B"
],
"durationOfTemporary": "06",
"employmentRelationship": "0101",
"jobDescription": {
"fi": "**Donec a dolor at nunc gravida gravida.** Nulla lacinia
malesuada neque, eu tincidunt lacus lacinia a. Nulla cursus leo
nulla, eu consequat lectus feugiat sit amet. Cras dapibus augue
eu hendrerit placerat. Morbi sit amet bibendum ligula, sed
vehicula erat. Sed nisl nisl, ornare ut ultricies in, ornare ut
enim.
\n\n- praesent\n \n- dignissim\n \n- sagittis\n \n- lobortis\n
\n\nNullam ornare orci at feugiat dictum. Nullam porttitor nibh
non aliquam pretium. Duis sed purus neque. Ut nec tortor
placerat, vehicula mi at, tempor ligula. Nam quis nisi ex. Nam
dignissim risus quis viverra tempus. Nulla facilisi. Aliquam
efficitur auctor augue, ac gravida leo volutpat vitae. Aenean
vitae tortor ut urna scelerisque aliquam. Sed elit velit, mollis
id ante sit amet, eleifend suscipit nulla.",
"en": "**Donec a dolor at nunc gravida gravida.** Nulla lacinia
malesuada neque, eu tincidunt lacus lacinia a. Nulla cursus leo
nulla, eu consequat lectus feugiat sit amet. Cras dapibus augue
eu hendrerit placerat. Morbi sit amet bibendum ligula, sed
vehicula erat. Sed nisl nisl, ornare ut ultricies in, ornare ut
enim.
\n\n- praesent\n \n- dignissim\n \n- sagittis\n \n- lobortis\n
\n\nNullam ornare orci at feugiat dictum. Nullam porttitor nibh
non aliquam pretium. Duis sed purus neque. Ut nec tortor
placerat, vehicula mi at, tempor ligula. Nam quis nisi ex. Nam
dignissim risus quis viverra tempus. Nulla facilisi. Aliquam
efficitur auctor augue, ac gravida leo volutpat vitae. Aenean
vitae tortor ut urna scelerisque aliquam. Sed elit velit, mollis
id ante sit amet, eleifend suscipit nulla."
},
"mainOccupation": "http://data.europa.eu/esco/occupation/9bf4c8ea-e814-4772-ae31-0f29672dc497",
"marketingDescription": {},
"occupations": [
{
"uri": "http://data.europa.eu/esco/occupation/1de91afd-9da2-47ab-a7e7-19bf931709a4"
},
{
"uri": "http://data.europa.eu/esco/occupation/7ed2e153-8da8-4c0d-b4c5-3402c623f34b"
}
],
"partTimeInfo": {
"fi": "10-15 Orci varius natoque penatibus.",
"en": "10-15 Orci varius natoque penatibus."
},
"permitCards": [
"002"
],
"permitCardsDescription": {
"fi": "Curabitur non tristique nunc. Nam at rutrum tellus.
Vestibulum interdum ut leo at gravida. Aliquam non nunc lectus.
Nam et bibendum lorem, id euismod nisl.",
"en": "Curabitur non tristique nunc. Nam at rutrum tellus.
Vestibulum interdum ut leo at gravida. Aliquam non nunc lectus.
Nam et bibendum lorem, id euismod nisl."
},
"skills": [
{
"uri": "http://data.europa.eu/esco/skill/00506f28-e884-4496-800c-3477c67eb355"
},
{
"uri": "http://data.europa.eu/esco/skill/2e2bde69-09df-45f7-88f4-a938717bee04"
}
],
"title": {
"fi": "Pellentesque vitae eros aliquet",
"en": "Pellentesque vitae eros aliquet."
},
"wagePrinciple": "0101",
"wagePrincipleInfo": {
"fi": "Nunc a dui sed.",
"en": "Nunc a dui sed."
},
"wageRange": "12",
"workLanguages": [
"fi",
"en"
],
"workTime": "01",
"workTimeDetails": [
"01",
"02"
]
},
"recruiter": {
"contactInfoVisible": true,
"contacts": [
{
"email": "lorem@ipsum.com",
"firstName": "Lorem",
"lastName": "Ipsum",
"telephone": "+358401234567"
}
]
}
}
Työpaikkailmoitukseen liittyvät erilaiset koodistoarvot ovat saatavilla Työmarkkinatorin koodistopalvelusta. Alla on kuvattu eri tietojen koodistot. Myös OpenApi-kuvauksessa on tieto attribuuttiin liittyvästä koodistosta.
Koodiston json-rakennetta luetaan siten, että koodiarvot löytyvät tunnus-elementistä ja tunnukseen liittyvä kuvaus
lokalisoituna selite-elementistä. Jokaiseen koodiarvoon liittyy myös voimassaoloaika. Koodistossa saattaa olla siis
koodiarvoja, jotka on jo poistettu käytöstä. Tälloin koodeilla on loppupaiva-tieto. Joillain koodistoilla voi olla
laajennuksia, joilla koodiston hyödyntämistä voidaan tarkentaa. Esimerkiksi osajoukko-laajennuksella halutaan rajata
vain tietyt kooditunnukset tiettyyn tarkoitukseen. Järjestysnumero-laajennus kertoo koodien halutun järjestyksen
esimerkiksi valintalistoissa.
| Päivämäärä | Muutoksen kuvaus |
|---|---|
| 10.3.2026 | Ensimmäinen versio |