Jobly.fi logo
Jobly.fi
Job Posting API Documentation
 (Previously known as Monster.fi)

Version 2.0.10 - 2024-01-01
General

Jobly Job Posting API enables you to add, update and delete jobs easily using our API.
Data is sent using HTTP POST requests. Each request contains one job ad data in XML format.

API Endpoints

There are two endpoints to add and delete jobs

  1. ADD one new job:

    https://www.jobly.fi/api/v1/job?key=[APIKEY]&action=add

    The HTTP body needs to contain all information of the job ad, including a job id. See the next chapters for more information on the data structures.

    To UPDATE data of an existing job you can use the ADD action and re-submit the job with the same id again. All data fields of the existing job will be overwritten.


  2. DELETE existing job:

    https://www.jobly.fi/api/v1/job?key=[APIKEY]&action=delete&id=[job_id]

    The DELETE requests need to contain the ID of the job you want to delete as URL GET parameter. The ID needs to be same as you provided in the XML in the ADD request. The HTTP body can be empty in this case.

    The DELETE action means the job is deactivated on the job board (unlisted in job search), but remains in the database, as long as no cleanup of outdated jobs has been performed. You can re-add/activate a job by using the ADD action.


Notice! In API endpoints use https instead of http or redirect will lose the job in POST message.


Responses

The API endpoints will return one of the following HTTP status codes:

  • Code 200
    Successful request.

  • Code 400
    Bad request (e.g. error in XML format). More information will be provided in the response body.

  • Code 403
    Access denied. Something went wrong with authentication (see authentication chapter below).

  • Code 404
    Job which should be deleted has not been found.

  • Code 423
    Delete request can’t be handled now. Try again later.

  • Code 5xx
    Any other error that occurred on the server. In addition, the response body contains a simple XML with more information (e. g. error message).

NOTE:

Jobly Job Posting API uses a queue system to publish and expire job ads. There may be a delay of a few minutes until your transaction is executed.

In addition, Jobly.fi frontend is cached up to 30 minutes for anonymous users. Please keep this in mind when finding the job ads for your transactions.

Authentication

Authentication is done using an API key that needs to be provided as GET parameter (?key=) in the URL. In addition, the key may be restricted to your IP addresses. Furthermore, if the credit check is enabled for your API key, a credit check based on the "uid" provided will be done. Insufficient credits will result in a 403 error.

Job Display Types

Job display type is set per API key.

Job per template
Default job display type is per API key is "Job per template". This job type will display content of "description" field in content area.

Job per link
Job display type can be set per API key also to "Job per link". In this case content of field "job_url" will be displayed in iframe tag instead of job content area.

Notice! We only use Job per template option.

Data Format

All data exchange happens via the XML format (Content-Type: text/xml in HTTP request). The XML must be valid, UTF-8 encoded and contain information on one single job ad. For delete requests the HTTP body can be left empty. 

						
<?xml version="1.0" encoding="UTF-8"?>
<job>
   <!-- JOB FIELDS SEE BELOW -->
</job>
Data Structure (Fields)

Data within the XML tags must be escaped or wrapped in CDATA to avoids conflicts with special characters, like "<" or "&".



Name XML Tag Type Required Additional information
Job ID id text yes Job ID as reference for update and delete. Maximum 255 character.

Job ID must be unique per publishing system. Not unique per customer.

Id tag must contain only letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).

Do not use hashtag symbol (#) in Job ID!
If you use a job ID which contains '#' it is not URL friendly, because # is reserved for fragments in the URL.
https://en.wikipedia.org/wiki/URI_fragment

For example delete request to:
/api/v1/job?key={api_key}&action=delete&id=0001#00037535

will be received by the API as id=0001 fragment=00037535 and incorrectly the job with the ID "0001" will be deleted.
User ID token uid text yes If your endpond has this feature enabled, this will allow the job assignment to user, based on the token provided.

UID is required per recruiter user only once the credit check feature is enabled. This allows for content admins to generate a uid token. This can be optional to all or for specific multiposters.
Title title text yes Title of the job. 255 chars limit.
Company name company text no Company name for job. 255 chars limit.
Company logo company_logo URL no Publicly accessible URL to logo in PNG, GIF, JPG or JPEG format.
Country country text no Country code (ISO 3166-1 alpha-2)

Can also be given full country name in English instead of alpha-2 code.

Not mandatory but important info for every job ad.
Location location text no City or region name.

Notice! When using multiple locations use semicolon (;) as separator.

Highly recommended to set location as it is used to target job ads in different marketing purposes.
ZIP Code zip_code text no Additional ZIP code for a more detailed location. Strongly recommend, pass ZIP code whenever available.
Application Type application_type text no Allowed case sensitive enumeration values:
  • external
  • internal
"external" (default, means redirect to URL provided in application_url)

"internal" (means Jobly.fi built-in application system with notification to email provided in application_email)
URL to external application system application_url URL no If application_type is "external", URL to redirect user when clicking the Apply button
Email address for internal application system application_email Email no If application_type is "internal", email to notify if user applies via built-in application system
Job Description description text yes Simple formatted text.
Following HTML tags are allowed:
<p> <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd> <br>
Job URL job_url URL yes URL of job that will be displayed in content area. Required only for "Job per link" importers.
Job Language lang text no Language the job is written in. Use RFC 5646 codes.
Employment type employment_type text no Allowed values see chapter Field Values, defaults to "Full time"
Occupation occupation text no Allowed values see chapter Field Values.

Highly recommended to set occupation field mandatory as it is used to target job ads in different marketing purposes.
Required degree level degree_level text no Allowed values see chapter Field Values
Years of experience (range) years_of_experience text no Allowed values see chapter Field Values
Salary range salary_range text no Allowed values see chapter Field Values
Required languages languages text no Allowed values see chapter Field Values
Required skills skills text no Allowed values see chapter Field Values
Job perks job_perks text no Allowed values see chapter Field Values
Industry job_industry text no Allowed values see chapter Field Values
Fields of study fields_of_study text no Allowed values see chapter Field Values
Job type job_type text no Allowed case sensitive enumeration values:
Job type label Enumeration value
Reach reach
Subs subs
Basic basic
Attract attract1
Attract+ attract2
Attract++ attract3
If value is not given it will use default value which is set to customer in Jobly system. Job type cannot be changed when updating already published job ad.
Job template ID job_template_id text no Template ID. If value is not given it will use default value which is set for customer in Jobly system.
Paid job template type job_template_type text no Allowed case sensitive enumeration values:
  • basic
  • paid_image
  • paid_video
If no value is sent the default is "basic" and job template is used if customer have any.

paid_image value allow to use job specific top and bottom images.

paid_video value allow to use job specific video on top and bottom image.

Image and video templates are available only for customers who have paid for license.
URL to the video job_template_video text no Only Youtube and Vimeo links are supported.

Notice!
"paid_video" value must be set in field "job_template_type".
URL to the top image job_template_image_top text no Publicly accessible URL to logo in JPG or PNG format.

Notice!
"paid_image" value must be set in field "job_template_type".
URL to the bottom image job_template_image_bottom text no Publicly accessible URL to logo in JPG or PNG format.

Notice!
"paid_video" or "paid_image" value must be set in field "job_template_type".
Job expiration date expiration_date date
ISO 8601		 no Allow you to define the expiration date of the job.
Date must be in ISO 8601 format.
YYYY-MM-DDThh:mm:ssTZD

YYYY = four-digit year
MM = two-digit month (01=January, etc.)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
TZD = time zone designator (+hh:mm or -hh:mm)

Example: If expiration is wanted to occur at 2nd of November in year 2022 at 23:00 in Finland time zone which is UTC +2 (at winter time).
Expiration date value would be:
2022-11-02T23:00:00+02:00

Notice! Time zone designator UTC value may vary in countries which use different winter time and daylight saving time. For example in winter time Finland use UTC +2 and in daylight saving time (summer) UTC +3.

If a job is published with an expiration date that is longer than the maximun allowed expiration date (60 days), the expiration date is automatically set in our system to the maximum allowed expiration date.

If a recruiter tries to update the expiration date of an already published job to a date later than the max expiration date, no change will be done. The initial expiration date that was posted for the first time will remain.

Examples

Add new job ad

HTTP POST: https://www.jobly.fi/api/v1/job?key=[APIKEY]&action=add 

							
<?xml version="1.0" encoding="UTF-8"?>
<job>
  <id><![CDATA[123]]></id>
  <uid><![CDATA[1_token]]></uid>
  <title><![CDATA[Java Developer]]></title>
  <company><![CDATA[Some company name]]></company>
  <company_logo><![CDATA[https://example.com/link-to-logo.png]]></company_logo>
  <country><![CDATA[UK]]></country>
  <location><![CDATA[London]]></location>
  <zip_code><![CDATA[EC1N]]></zip_code>
  <application_type><![CDATA[external]]></application_type>
  <application_url><![CDATA[http://example.com/link-to-apply]]></application_url>
  <job_url><![CDATA[http://example.com/jobs/example-job-123]]></job_url>
  <description>
    <![CDATA[
      <p>We are looking for a Java developer at...</p>
      <p><strong>Qualifications:</strong></p>
      <ul>
        <li>Pursuing a M.S. degree in Engineering, Computer Science, or related field</li>
        <li>Excellent programming skills, preferably Java</li>
        <li>Familiarity with data structures and algorithms.</li>
      </ul>
    ]]>
  </description>
  <lang><![CDATA[en-GB]]></lang>
  <employment_type><![CDATA[Full time]]></employment_type>
  <fields_of_study><![CDATA[Computer science / IT]]></ fields_of_study >
  <occupation><![CDATA[Software Development]]></occupation>
  <occupation><![CDATA[IT]]></occupation>
  <degree_level><![CDATA[Master]]></degree_level>
  <years_of_experience><![CDATA[3 - 5 years of experience]]></years_of_experience>
  <salary_range><![CDATA[3000 - 4000 €]]></salary_range>
  <languages><![CDATA[English]]></languages>
  <skills><![CDATA[IT Management]]></skills>
  <job_perks><![CDATA[Requires travel]]></job_perks>
  <job_industry><![CDATA[Computer Software]]></job_industry>
  <job_template_type><![CDATA[paid_video]]></job_template_type>
  <job_template_video><![CDATA[https://www.youtube.com/watch?v=FP6hLgCndTo]]></job_template_video>
  <job_template_image_top><![CDATA[https://example.com/link-to-logo.png]]></job_template_image_top>
  <job_template_image_bottom><![CDATA[https://example.com/link-to-logo.png]]></job_template_image_bottom>
  <expiration_date>2022-09-02T23:00:00+02:00</expiration_date>
</job>

Delete job ad

HTTP POST: https://www.jobly.fi/api/v1/job?key=[APIKEY]&action=delete&id=123

<no body needed>

Field Values

This chapter contains a list of URLs to retrieve the list of allowed values for each field, e. g. for employment type. The URL callbacks return the values in a human-readable format (HTML page).

If you leave a field empty, the system will try to automatically classify it based on the job title and description. Still, it is better to explicitly provide the values, if possible.

In case you have multiple values per field you need to comma separate the values wrapped inside CDATA. 

						
<employment_type><![CDATA[Full time, Part time]]></employment_type>

Another and maybe more clear option to send multiple values is to use multiple same name tags and send the value wrapped inside CDATA. 

						
<employment_type><![CDATA[Full time]]></employment_type>
<employment_type><![CDATA[Part time]]></employment_type>

CDATA is needed to help avoid posting invalid XML. Some values contain special characters as '&' which makes XML invalid unless the value is escaped or wrapped inside CDATA.

You can send the values in the text format how they appear in the list as there are no IDs for values. We offer values in Finnish and English. Values are in same order no matter which language list you look. For example, the last value in Finnish version list is the same value as the last value in English version list.

Taxonomy Field Values

Taxonomy values are listed in Finnish and in English. You can use them both if your ATS is offering both languages in UI.
There are no ID's for values. Post values directly to API as they are offered. Finnish and English values are in same order so you can match which one is which in different languages.

Employment type
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=employment_type
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=employment_type

Fields of study
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=fields_of_study
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=fields_of_study

Occupation
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=occupational_fields
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=occupational_fields

 Notice! Occupational fields have two level hierarchy.
 As the second level values are constantly evolving list we suggest ATS to allow user to select only first level values.
 The second level values are automatically selected for job on Jobly.fi backend based on job ad data.

Required degree level
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=degree_level
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=degree_level

Years of experience
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=years_of_experience
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=years_of_experience

Salary range
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=salary_range
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=salary_range

Required languages
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=languages
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=languages

Required skills
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=general_skills
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=general_skills

 Notice! Required skills have two level hierarchy.
 First level value is only title for the skills under it in the second level.
 Second level skill values are the values which could be selected to be sent with job posting.

Job perks
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=job_perks
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=job_perks

Industry
Finnish: https://www.jobly.fi/api/v1/catalogues?key=[APIKEY]&voc=industry_fields
English: https://www.jobly.fi/en/api/v1/catalogues?key=[APIKEY]&voc=industry_fields

Help to start implementing the integration

Here is the basic knowledge you need to start building the integration.
If you face any problems please don't hesitate to send email to job board administrator in email tech@jobly.fi

API KEY for integration

ATS specific API KEY to allow jobs to be published. Provided by job board administrator.

User API token for customer

Customer specific API Token for credit check. Provided by Jobly.fi customer service.
While implementing integration, job board administrator can provide API Token for test customer.

Customer JOB Template ID's

One or more customer specific job templates. Provided by Jobly.fi customer service.

NOTICE!

At the moment we do not have demo site for integration testing purposes so basically everything is going live on production site https://www.jobly.fi and are published about in couple of minutes.

Please keep in mind to keep test job ad text appropriate and if possible, send delete request as soon as possible after successful add request after you have checked how your test posting looks in Jobly.fi job board.

Version History

Version 2.0.10 - 2024-01-01

  • Job type values are updated to match 2024 Jobly.fi products.

Version 2.0.9 - 2023-02-21

  • New occupational field value added:
    English value: "Environment and sustainability"
    Finnish value: "Ympäristö ja vastuullisuus"

Version 2.0.8 - 2023-01-03

  • Old job types removed (standard, premium, smart and brand)
  • New job types added (reach, attract1, attract2 and attract3)
  •    reach = Jobly Reach
  •    attract1 = Jobly Attract
  •    attract2 = Jobly Attract+
  •    attract3 = Jobly Attract++

Version 2.0.7 - 2022-10-25

  • New brand and domain Jobly.fi (previous known as Monster.fi) and API endpoint URL changed
  • New values added to job_type enumeration list: reach, attract1, attract2 and attract3

Version 2.0.6 - 2022-09-02

  • New field added: expiration_date

Version 2.0.5 - 2022-06-08

  • New value added to Employment type taxonomy vocabulary.
    Finnish: "Hybridityö"
    English: "Hybrid work"

Version 2.0.4 - 2022-05-06

  • New 1st level occupational field taxonomy vocabulary value "Suitable for refugees". It is meant for job ads which are positions where refugees can easily apply. Taxonomy value is only in English.

Version 2.0.3 - 2022-04-07

  • Occupational field taxonomy vocabulary expanded to more detailed two level hierarchy. Second level values are set to jobs automatically on Jobly.fi backend based on job ad data.

Version 2.0.2 - 2022-03-21

  • New value "Startup" in taxonomy vocabulary Job Perks.
  • Online version of API documentation.

Version 2.0.1 - 2022-01-19

  • New API response Code 423 Locked with message "Delete request can’t be handled now. Try again later."
    Occurs rarely when API is too busy to handle all requests at the same time. Usually delete requests.
  • Country and location fields are not mandatory anymore, but it is still good to set location(s) for job.

Version 2.0 - 2021-12-23

  • New fieds for adding images and video to job: job_template_type, job_template_video, job_template_image_top and job_template_image_bottom. Image and video templates are available only for customers who have paid for license
  • In country field user can give country code (ISO 3166-1 alpha-2) but field also accepts full country name in English. In some rare cases, this helps google geocode to match location better to correct country as there are some similar location names in different countries.
  • New "Employment type" value made for summer jobs.
    English value: "Summer job"
    Finnish value: "Kesätyö"
  • "Fields of study" there was extra space in the end of couple of Finnish version values.
    "Biologia" and "Esittävät taiteet". Spaces removed. ATS should check your data too if ATS is not using the values directly from the given URL where list is found.
  • Company name field was mistakenly required. It is optional field.

Version 1.9 - 2021-05-21

  • Some fixes in taxonomy vocabulary fields.

Version 1.8 - 2021-04-13

  • New fields added: job_type, job_template_id