This documentation specifies the technical requirements of the Jobposting Management API for job Market Finland and
describes in more detail how to use the actual API. The onboarding process for the API is explained in more detail on
Job Market Finland website. The OpenAPI descriptions
for the P66 interface related to jobposting management can also be found there.
Jobpostings from exernal services can be published and managed on Job Market Finland via this interface. Jobpostings can also be scheduled for publication. Published jobpostings can be edited and archived via the interface.
The jobposting management API is designed so that the user of the interface does not need to be the actual employer of the job,
but can use it to manage jobpostings from several different companies. The jobposting is created for the company specified
in the businessId parameter in the URL.
The interface for managing jobpostings at the Job Market Finland is provided via the KEHA Center's integration platform (Kipa). The credentials for using the integration platform and the related IP addresses are provided by the KEHA Center as part of the interface implementation process. The credentials required for using the interface are delivered to the interface user securely. More detailed information about the implementation can be found on the Job Market Finland website.
Detailed processes related to jobposting management are illustrated in the diagram below.
Actual management of jobpostings is done through the P66 service of the Kipa integration platform, which connects to
Job Market Finland's backend service. Available functions, data structure, and responses are described in the
management API YAML description.
Calls through the Kipa integration platform are authorized using an API key mechanism, and the header information of
the request must include the KIPA-Subscription-Key provided for Kipa usage. Header attribute KIPA-MessageId is set
automatically by the interation platform.
The P66 service of the Kipa integration platform can be found at the following addresses:
https://api-qa.ahtp.fi/kipa/p66/v1/jobpostinghttps://api.ahtp.fi/kipa/p66/v1/jobpostingJobpostings are managed via the /v1/jobposting/{businessId}/{externalId} API endpoint. The
HTTP method used specifies the action being performed on the jobposting. The options are retrieving jobposting data
(GET), creating or updating a jobposting (PUT), or deleting a jobposting (DELETE).
The jobposting’s unique uuid-formatted externalId identifier must be provided in the API call when creating a jobposting
to the Job Market Finland.
If you want to update an existing jobposting, you must add an If-Match header to the request, specifying the value of the etag field from the jobposting’s data.
This ensures that the latest version of the jobposting is processed. If the etag value does not match the value in the database, the job posting has been modified since the data was retrieved, and the update will fail. To ensure the update succeeds, it is recommended to retrieve the jobposting data using the GET method before attempting the update.
Jobpostings can be imported to the Job Market Finland either directly in published status or pending publication at a
specific time. Published or pending jobpostings can be updated. Jobpostings are automatically removed from publication
at the end of the application period or can be removed using the DELETE method. In both cases, the josposting is moved
to an archived status and is no longer public. If a jobposting contains inappropriate content and the authorities prevent
its publication, the status of the advertisement is changed to blocked, after which it can no longer be processed via
the administration interface.
Jobpostings can be submitted in three languages, and the languages used must be specified using the languages attribute.
The localized free text fields are validated to ensure that they contain translation elements in all languages specified
in the jobposting. If this is not the case, the jobposting will be rejected.
Jobpostings use the European ESCO classification to describe occupations and skills. A national extension (FINESCO) has been made to the classification, which includes the latest ESCO classification and national occupations added to it. The use of FINESCO ensures that jobpostings can also be transferred to the European Employment Services (EURES) portal. The FINESCO classification is available on the Job Market Finland website.
With regard to occupational data, it should be noted that jobposting data is compiled in the Employment Service Statistics.
However, only one occupation can be provided there, even if the jobposting allows multiple occupations. For this reason,
the occupation used for statistical purposes in jobposting imported via the interface is taken from
the first item in the occupations list, if there is no value in the mainOccupation field.
In the jobposting, the skills required for the job are optional information. It is recommended to fill in the skills required, as they are used to match jobpostings and job applicant profiles.
The location in the jobposting must be specified as at least one municipality, but it is possible to specify other locations as well. Municipality information is required so that the jobposting is classified to the right employment authority.
The jobposting data model consists of the elements shown in the figure below. Mandatory information is indicated in bold
text. For missing information, the structure must either be null or the key must be omitted entirely.
Below is an example of the structure of a jobposting when creating a new jobposting to the service.
{
"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"
}
]
}
}
Different codeset values related to the jobpostings are available from the Job Market Finland's codeset service. The codesets of different type of data are described below. The OpenApi description also contains information about the attributes related to the code values.
The json structure of the codeset is read in such a way that the code values can be found in the tunnus element and
the description related to the id localized in the selite element. Each code value also has a validity period. The
codeset may therefore contain code values that have already been removed from use. In such cases, the codes have
loppupaiva information. Some codesets may have extensions that can be used to refine the use of the codeset. For example,
the osajoukko extension is used to limit only certain codes to a specific purpose. The Järjestysnumero extension
indicates the desired order of the codes, for example in selection lists.