Technical Solutions

Home
ATS Partners
Crawler interface
Easy Apply ATS Integration
JSON interface
XML interface

Importing Standardized JSON Feed Format (valid from 2026)

 

This document outlines the standardized JSON feed format used for importing job advertisements into our system and publishing them across JobCloud platforms. It defines the required data structure, validation logic, and operational flow to ensure reliable and automated integration between your system and ours.

Scope
Data source: Client provides a JSON feed with job ads.
Delivery model: Our system periodically pulls the feed via a stable HTTP(S) endpoint.
Validation: All records are checked against the official JSON Schema and business rules.
Publishing & lifecycle: Valid ads are created/updated; ads missing from subsequent fetches are automatically deactivated.

Operational details
Endpoint: Public or protected HTTP(S) URL without manual login (automation-ready). Basic auth, token, or mTLS by agreement.
Fetch cadence: ~Every 3 hours (partner-specific configuration).
Communications: Initial setup and configuration changes via service@jobcloud.ch.
Error handling: Invalid records are skipped with reason logged; critical fetch errors trigger retries with backoff.

Lifecycle rules
Create/Update: Ads are identified by externalId (optionally combined with externalCompanyId). Changes in the feed are reflected on published ads.
Deactivation: Ads no longer present in the feed are set to inactive/stopped in the next processing cycle.
Versioning: The feed should expose a schema version (e.g., schemaVersion) to enable safe future changes.

Security & availability
Transport: HTTPS required; TLS 1.2+ recommended.
Authentication: Basic, Bearer token, or mTLS (agreed during onboarding).
Stability: The endpoint must be highly available and resilient to brief outages.

JSON feed fields (schema references)
Full list and types are provided and linked in the accompanying JSON Schema.

Example of JSON Feed containing 1 job ad:

{

"jobAds": [

{

"externalCompanyId": "company-123",

"externalId": "job-001",

"jobPosition": "Software Engineer",

"employmentGradeFrom": 80,

"employmentGradeTo": 100,

"metadataApiEmploymentTypeId": 1,

"metadataApiEmploymentPositionId": 12345,

"description": "Develop and maintain software applications.",

"application": {

"externalUrl": "https://apply.example.com/job-001"

},

"address": {

"city": "Zurich",

"postalCode": "8001",

"countryIsoCode": "CH",

"street": "Bahnhofstrasse 1",

"addition": "5th Floor",

"latitude": 47.3769,

"longitude": 8.5417

},

"language": "EN",

"languageRequirements": [

{

"metadataApiLanguageId": "en",

"metadataApiLanguageLevelId": 3

}

],

"experience": "1-3",

"salaryUnit": "YEAR",

"salaryFrom": 60000,

"salaryTo": 90000,

"showSalary": true,

"videos": [

{

"url": "https://youtube.com/examplevideo1"

}

],

"recruiter": {

"firstName": "Alice",

"lastName": "Smith",

"profilePictureMediaApiId": "https://media.jobs.ch/images/recruiter.jpg"

},

"jobGroupId": "jobgroup-01",

"logoMediaApiId": "https://media.jobs.ch/images/image.png",

"headerMediaApiId": "https://media.jobs.ch/images/banner.png",

"product": "JOBSOFFER22M"

}

]

}


externalCompanyId

Field Name externalCompanyId
Description An identifier used to reference the company either in the customer’s external system (External ID) or in our former system (ORGANISATIONID or ZLOGIN), or a new account ID (specified by JobCloud team, can be requested).
Field Type string
Mandatory Field no

externalId

Field Name externalId
Description Unique identifier for a job ad from the client’s system (f.e. ATS). Used to ensure correct reference and integration. The field accepts a maximum of 255 characters.
Field Type string
Mandatory Field yes

jobPosition

Field Name jobPosition
Description Job title. The field accepts a maximum of 255 characters.
Field Type string
Mandatory Field yes

description

Field Name description
Description Text description of the job ad containing details such as tasks and requirements. You may format the text using the following supported HTML tags: <a>, <b>, <br>, <em>, <h1>–<h6>, <li>, <p>, <strong>, <ul>, <ol>, <u>.
Field Type string
Mandatory Field yes

employmentGradeFrom

Field Name employmentGradeFrom
Description Minimum employment percentage (minimum 0; default 100).
Field Type integer
Mandatory Field yes

employmentGradeTo

Field Name employmentGradeTo
Description Maximum employment percentage (minimum 0; default 100).
Field Type integer
Mandatory Field yes

metadataApiEmploymentTypeId

Field Name metadataApiEmploymentTypeId
Description The ID of the employment type. Allowed values are:
1 = Temporary. Fixed-term employment for a specific period or project.
2 = Freelance. Project-based work or collaboration with independent worker.
3 = Internship. Temporary work for students or recent graduates to gain practical experience.
4 = Supplementary income. Part-time or flexible work arrangement that provide additional income alongside other primary sources or earnings.
5 = Unlimited employment. Full-time employment with no predetermined end date.
6 = Apprenticeship. Training program that combines in-the-job learning with classroom instruction.
Field Type integer
Mandatory Field yes

application

Field Name application
Description URL to the application form for the job ad. Links to our “Apply” button. Clicking on the button opens the external URL in a new tab. Upon request, the Easy Apply feature can be used instead of an external URL.
Field Type string($uri)
Mandatory Field yes

address

Field Name address
Description Address object with multiple fields:
city: “City name”
postalCode: “XXXX”
countryIsoCode: “CH”
street: “Street name with number”
addition: “Additional info about the address”
longitude: 47.36777
latitude: 8.5594489
The fields ‘city’ and ‘postalCode’ are mandatory. If they are not provided, the account address on our platform will be used as the default address on job level.
Field Type city: string
postalCode: string
countryIsoCode: string
street: string
addition: string
longitude: number($float)
latitude: number($float)
Mandatory Field yes

metadataApiEmploymentPositionId

Field Name metadataApiEmploymentPositionId
Description The ID of the employment position. Allowed values:
1 = Executive position
2 = Position with responsibilities
3 = Employee
Field Type integer
Mandatory Field no

language

Field Name language
Description Language code of the job ad content. Allowed values:
DE = German
EN = English
FR = French
IT = Italian
Field Type string
Mandatory Field no

languageRequirements

Field Name languageRequirements
Description List of required languages and levels [{metadataApiLanguageId, metadataApiLanguageLevelId}]

Allowed values (a selection) for metadataApiLanguageId:
de = German
fr = French
en = English
it = Italian

Allowed values for metadataApiLanguageLevelId:
1 = Basic knowledge
2 = Intermediate
3 = Fluent
4 = Native language
Field Type string
Mandatory Field no

experience

Field Name experience
Description Professional experience. Specify the years of experience the candidate should have in a similar position. Allowed values (in years):
0-1
1-3
3-5
5-7
7+
Field Type string
Mandatory Field no

salaryUnit

Field Name salaryUnit
Description Unit of salary measurement (in order for salary information to be displayed correctly, all fields must be transmitted with correct values). Allowed values:
YEAR
MONTH
WEEK
HOUR
Field Type string
Mandatory Field no

salaryFrom

Field Name salaryFrom
Description Minimum salary amount (in order for salary information to be displayed correctly, all fields must be transmitted with correct values).
Field Type integer
Mandatory Field no

salaryTo

Field Name salaryTo
Description Maximum salary amount (in order for salary information to be displayed correctly, all fields must be transmitted with correct values)
Field Type integer
Mandatory Field no

showSalary

Field Name showSalary
Description Whether the salary should be displayed (in order for salary information to be displayed correctly, all fields must be transmitted with correct values). Allowed values:
true
false
Field Type boolean
Mandatory Field no

videos

Field Name videos
Description List of video objects, each with a URL. Youtube or Vimeo link (no “shorts”). The video must allow external embedding.
Field Type string($uri)
Mandatory Field no

recruiter

Field Name recruiter
Description Object with recruiter’s first and last name (required), and optional profile picture ID e.g. { “firstName“: “John”, “lastName“: “Brown” }

Allowed format for profilePictureMediaApiId:
The URL of the picture is transmitted and included in the job ad.
“min_width”: 224,
“min_height”: 224,
“min_ratio”: 0.9,
“max_ratio”: 1.1,
“max_size”: “20m”

Available file types: avif, gif, jpeg, png, webp. If the picture from the URL does not pass any of these validation parameters, it will be discarded, and the job ad will be published without it.
Field Type firstName: string
lastName: string
profilePictureMediaApiId: string($uuid)
Mandatory Field no

recruiterId

Field Name recruiterId
Description Uuid of existing user from platform (specified by JobCloud team, can be requested).
Field Type string($uuid)
Mandatory Field no

jobGroupId

Field Name jobGroupId
Description Uuid of existing jobGroup (specified by JobCloud team, can be requested). Job postings can be split in different groups, by this group ID (for example: all job ad’s with location in Geneva vs. Zurich, or brand name 1 vs. brand name 2, etc.). Job Groups will be created by JobCloud team.
Field Type string($uuid)
Mandatory Field no

logoMediaApiId

Field Name logoMediaApiId
Description A media API resource ID. The URL of the logo is transmitted and included in the ad. Format specifications:
“min_width”: 320,
“min_height”: 320,
“min_ratio”: 0.9,
“max_ratio”: 1.1

Available file types: avif, gif, jpeg, png, webp. The focus of the logo should be in the center of the image. Images that are too large will be scaled down proportionally (no image cropping). Images that are too small will be rejected (the job ad will still go online). In principle, we recommend that you do not deviate from this format in order to achieve optimum results. The website must allow the file to be downloaded (no restriction of the user agent).
Field Type string($uuid)
Mandatory Field no

headerMediaApiId

Field Name headerMediaApiId
Description A media API resource ID. The URL of the banner is transmitted and included in the ad. Format specifications:
“min_width”: 1200,
“min_height”: 400,
“min_ratio”: 2.9,
“max_ratio”: 3.1,
“max_size”: “32m”

Available file types: avif, gif, jpeg, png, webp. The focus of the banner should be in the center of the image. Images that are too large will be cropped proportionally from the center of the image. Images that are too small will be rejected (the job ad will still go online). In principle, we recommend that you do not deviate from this format in order to achieve optimum results. The website must allow the file to be downloaded (no restriction of the user agent).
Field Type string($uuid)
Mandatory Field no

product

Field Name product
Description Fixed offer allocation for the job ad’s. Mandatory, if several products have been purchased. List:
JS24FREE
JS24PLUS
JS24ADVANCED
JS24SOLO
JS24BASIC
JOBSSTARTER
JOBSSTANDARD
JOBSLIMITED
JOBSFLEX
JOBSOFFER22FREE
JOBSOFFER22XS
JOBSOFFER22S
JOBSOFFER22M
JOBSOFFER22L
JOBSOFFER22XL
JOBUP24FREE
JOBUP24LITE
JOBUP24BASIC
JOBUP24ADVANCED
JOBUP24ULTIMATE
JOBUP24ULTIMATEPLUS
PAYPERPERFORMANCE
SLOTJOBSBASIC
SLOTJOBSADVANCED
SLOTJOBSULTIMATE
SLOTJOBSULTIMATEPLUS
SLOTJOBUPBASIC
SLOTJOBUPADVANCED
SLOTJOBUPULTIMATE
SLOTJOBUPULTIMATEPLUS
Field Type string($uuid)
Mandatory Field yes


FAQ

At what times does the interface read my job ads?
We can define specific intervals per client (default: every 3 hours).

Can my JSON feed be password-protected?
In the current implementation of feed importers it’s not supported, though we plan to allow it in the future.

Can the URL of my JSON feed change?
The URL of the JSON feed must stay the same and cannot be redirected.

CONTACT

If you have any further questions, please don’t hesitate to contact us:
Team Product Support
service@jobcloud.ch
P +41 44 254 69 09