The Job-Room Jobs API

1. Latest change: November, 2022

  • Occupation codes: Use the most recent AVAM occupation code list. The relevant codes are in column D, not column A.

  • Filtering by status: You can now filter job ads by status (Filter by status)

  • Access token: On creation of a job ad, you get an Access token back as a header which allows the owner to view the job ad even if it is restricted.

2. Testing and productive access credentials

  • For testing:

  • The URL for the productive API is https://api.job-room.ch/jobAdvertisements/v1

    • Do NOT submit test data to the production environment!

  • If you have integrated and tested the Jobs API and wish to request productive access credentials:

    • Send a message with subject "Job-Room API access" to jobroom-api@seco.admin.ch

    • Specify the company name, address and email, at least one technical contact person with email address and phone number, and user name. Please also specify the expected volume of job registrations.

    • The technical contact will receive an email with further instructions.

3. Important notes

  • The recommended format for job descriptions is Markdown formating. You may use simple html tags as well but they will be converted to Markdown. Some markdown references you might find helpful:

  • Company address: While the Company address is not currently defined as mandatory, we strongly request that this data is included for jobs under reporting obligation. If the address is missing, this causes extra work for the public employment agent.

  • Postal code validation: The job location must have valid postal code and city data. Validation is based on the Swiss Post, refer to https://www.post.ch/en/pages/plz-suche.

  • Phone number validation: The minimum length of a phone number was reduced in order to accomodate Liechtenstein phone numbers. The format is [+][1-9][0-9]{7,18}.

  • You can find a list of language codes supported by Job-Room at List of supported languages

  • It is not possible currently to cancel a job advertisement in status INSPECTING. Only cancel job ads in status PUBLISHED_RESTRICTED or PUBLISHED_PUBLIC.

  • Updating a job ad is currently not supported.

4. General

The Job-Room Jobs API https://api.job-room.ch/jobAdvertisements/v1 provides an additional channel for employers to publish job advertisements to the Swiss public employment services system. It is an alternative to the web form available at https://www.job-room.ch/#/companies/jobpublication.

Companies that wish to use the jobs API will need to request access credentials.

For technical questions regarding the jobs API, use the contact address above. Please provide the name of the company and a technical contact person. For nontechnical questions (e. g. legal, administrative) regarding the job registration requirement, please refer to https://www.arbeit.swiss/secoalv/en/home/menue/unternehmen/stellenmeldepflicht.html.

5. Jobs registration process

Please read this section carefully as this will avoid many questions and problems!

Under the job registration requirement, from July 1 2018, employers must report job vacancies in Switzerland in certain occupations to the public employment services. The list of occupations that fall under the law can be downloaded from the arbeit.swiss portal. Regardless of the legal requirement, employers are invited to publish, free of charge, any vacancies on the public job search platforms of the Swiss public employment service - Job-Room (https://www.job-room.ch) and Job-Desk (http://www.job-desk.ch) - as well as on the European platform Eures (https://ec.europa.eu/eures/public/en/homepage).

The registration process via the Jobs interface (API) is as follows:

  • Job ads are published one by one using the Create method.

  • They are immediately assigned an id and a stellennummerEgov, both serve as unique identifiers within Job-Room.

  • All vacancies reported to the API must have an occupation code. Based on that code, the system determines whether the job falls under the registration requirement (see List of occupation codes)

  • If no: the job ad is directly published on Job-Room and will be visible and searchable to the public. The maximum publication period is 60 days. Job ads under publication can at any time be canceled via the API.

  • If yes: the flag reportingObligation is set to true and the job ad is transmitted to the database of the Swiss public employment service (PES), called AVAM. It is then reviewed and approved by a PES agent (there can be a delay). The competent job center (RAV) is indicated by the jobCenterCode. It may also be rejected, for example if information is insufficient.

  • After the ad is approved or rejected, an email to the contact person is generated with information about the registration requirement.

  • The ad may not be published elsewhere for a period of five work days from the date of approval. The last day of that period is indicated in the email message and in the property reportingObligationEndDate.

  • Approved ads are assigned an additional identifier, stellennummerAvam. In correspondence with PES or Job-Room support, stellennummerEgov is most useful but sometimes stellennummerAvam is helpful. These identifiers can also be used as search terms in the Job-Room job search.

  • During the blackout period, the ad is not visible to the public, only to registered job seekers.

  • After the blackout period, the ad is available to the public on Job-Room. The employer may opt out of this by setting the publicDisplay flag to false.

  • The owner of a job ad may at any time view the state of the data object using the Get method. Important: the properties stellennummerAvam and reportingObligationEndDate aren’t known at the time of submission and the status changes over the life cycle. To retrieve these properties, use the Get method after approval of the job ad. This applies only to those ads that go through validation by the Public Employment Service.

6. API

JobRoom API exposes a simple way to manage job advertisements. It follows RESTful standards like :

  • Actions on resources are performed through HTTP methods

  • Resources are exposed with JSON format

  • HATEOAS architecture is implemented with HAL standard

  • Basic HTTP authentication

  • Explicit HTTP status codes

  • Pagination support

The following chapters explain more precisely some of these concepts and provide examples in how to create, read, and cancel job offers.

7. HTTP verbs

The following verbs are fully supported :

Verb Description

GET

Used for retrieving resources, either a single object or a collection.

POST

Used for creating new resources or performing actions on resources.

PATCH

Used for updating existing resources.

8. HTTP response status codes

Status codes in HTTP responses follow REST standards.

The following table describes examples and precisions specific to JobRoom API :

Status code Name Description

200

OK

Success using GET for retrieving resources.

201

Created

Success using POST for creating new resources.

204

No Content

Success using POST for performing actions.

400

Bad request

Occurs when error in body using POST/PATCH (missing non nullable field, invalid JSON object, wrong object type, validation failed, etc.).

401

Unauthorized

Occurs when accessing to a protected resource with bad credentials.

403

Forbidden

The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource or action.

404

Not Found

Occurs when requested resource does not exist or when accessing another user’s resource.

500

Internal Server Error

Server encountered an internal error.

9. Headers

The following headers have to be set for some requests in order to use the API :

Header name Value When to use ?

Content-Type

application/json;charset=UTF-8

Every request.

Authorization

Basic <Base64 encoded credentials>

Always, all API endpoints require authentication (see section Authentication).

Accept

application/json;charset=UTF-8

Always.

10. Authentication

First, you need to get a username and password.

Authentication is done using HTTP Basic Auth.

Every request to the API must have a header Authorization with a value constructed like :
Basic Base64(username:password).
Value after Basic is a Base64 representation of the string containing the username and the password, separated by a colon.

Example :
username : user
password : password
The value of the Authorization header will be Basic dXNlcjpwYXNzd29yZA==.

11. Create a new job advertisement

11.1. Fields

11.1.1. JobAdvertisement

Path Type Description Constraints Notes

externalUrl

String(1024)

Link to the original website of the job ad

Optional

For jobs that fall under the reporting obligation, the ad must not be published elsewhere.

externalReference

String(255)

Your internal reference to this job ad

Optional

reportToAvam

Boolean

Should the ad be transmitted to the PES (RAV)?

Required (true or false)

Usually false. Use this option if you want a PES agent to know about your vacancy

numberOfJobs

String(3)

The number of identical positions

Optional

Use this option only if you have a number of identical vacancies. The number will be transmitted to the PES agent.

contact

Contact

Contact person about the job ad

Required

Administrative contact; not for publication, will be treated confidentially

jobDescriptions

Array<JobDescription>

Language specific title and description

Required 1..4

The text of the job advertisement; may be multilingual

company

Company

The company that handles the recruitment

Required

May be a private placement agency or hiring of services agency

employer

Employer

The actual employer that offers the job

Required, if company.surrogate is true

Not for publication, will be treated confidentially

employment

Employment

Certain employment conditions

Required

location

Location

The work location

Required

occupation

Occupation

Occupation, education and work experience

Required

languageSkills

Array<LanguageSkill>

It is possible to define up to 5 language skills required by the job.

0..5 objects

publicContact

PublicContact

Contact person for the job seekers questions

Optional

Will be published in Job-Room

applyChannel

ApplyChannel

Different application channels

Required

Provide at least one application channel

publication

Publication

The publication platforms

Required

You can control how your ad is published

11.1.2. Contact

Provide an administrative contact (e. g. an HR employee).

Important: this contact is used for email notifications concerning the reporting obligation. The contact details are not for publication and will be treated confidentially.

Path Type Description Constraints

languageIsoCode

String(5)

The language of correspondence

Required (ISO 639-1), must be one of de, fr, it,en

salutation

String(3)

Required (MR or MS)

firstName

String(50)

Required

lastName

String(50)

Required

phone

String(20)

Required (Format: +41123456789)

email

String(50)

Only one valid address allowed

Required

11.1.3. JobDescription

The text of the job advertisement; may be multilingual

Path Type Description Constraints

languageIsoCode

String(5)

The language of the title and description

Required (ISO 639-1) but only de, fr, it or en

title

String(255)

Job title or occupation

Required

description

String(10'000)

Job description cannot contain html formatting. Use markdown formating instead

Required (Max 10'000 characters)

11.1.4. Company

The company that handles the recruitment. This information is published.

Path Type Description Constraints

name

String(255)

The name of the company

Required

street

String(50)

Provide a street or post office box address

houseNumber

String(10)

Provide a street or post office box address

postOfficeBoxNumber

String(10)

Provide a street or post office box address

postOfficeBoxPostalCode

String(10)

Optional

postOfficeBoxCity

String(100)

Optional

postalCode

String(10)

Required. Must be a valid swiss postal code if the company is located in Switzerland

city

String(100)

Required

countryIsoCode

String(2)

Required (ISO 3166-1 alpha-2)

website

String(255)

Optional (Format: http://www.example.org)

phone

String(20)

Optional (Format: +41123456789)

email

String(50)

Only one address allowed

Optional

surrogate

Boolean

Does the company act as a surrogate for the actual employer?

Required (true or false)

11.1.5. Employer

If the recruitment is handled by a private placement agency or hiring of services agency, the company.surrogate flag MUST be set to true and the actual employer information MUST be provided. This information is required for administrative purposes and will be treated strictly confidentially by SECO and the Public Employment Service.

Path Type Description Constraints

name

String(255)

The name of the original company

Required

city

String(100)

Required

postalCode

String(10)

Required. Must be a valid swiss postal code if the company is located in Switzerland

countryIsoCode

String(2)

Required (ISO 3166-1 alpha-2)

11.1.6. Employment

Employment metadata

Path Type Description Constraints

startDate

String(10)

When does the job start

Optional (Format: 2018-01-20)

endDate

String(10)

When does the contract end

Optional (Format: 2018-01-20)

shortEmployment

Boolean

Is the employment duration 14 days or less

Required (true or false)

immediately

Boolean

Does the job start immediately

Required (true or false) true only if no startDate is set

permanent

Boolean

Is the contract permanent

Required (true or false) true only if no endDate is set

workloadPercentageMin

String(3)

Required (10..100 less or equal workloadPercentageMax)

workloadPercentageMax

String(3)

Required (10..100 greater or equal workloadPercentageMin)

workForms

Array<String>

Special work requirements

Optional (SUNDAY_AND_HOLIDAYS, SHIFT_WORK, NIGHT_WORK, HOME_WORK)

11.1.7. Location

Path Type Description Constraints

postalCode

String(10)

Required. Must be a valid swiss postal code if the company is located in Switzerland

city

String(50)

The (main) place of work

Required

countryIsoCode

String(2)

Required (ISO 3166-1 alpha-2)

11.1.8. Occupation

The ad must be coded to an occupation according ot the AVAM occupation list; this determines the reporting obligation.

Path Type Description Constraints

avamOccupationCode

String(16)

AVAM occupation code

Required

workExperience

String(64)

Optional (LESS_THAN_1_YEAR, MORE_THAN_1_YEAR or MORE_THAN_3_YEARS)

educationCode

String(8)

AVAM education code

Optional

11.1.9. LanguageSkill

Path Type Description Constraints

languageIsoCode

String(5)

Required (ISO 639-1)

spokenLevel

String(64)

Required (NONE, BASIC, INTERMEDIATE or PROFICIENT) (see Common reference levels)

writtenLevel

String(64)

Required (NONE, BASIC, INTERMEDIATE or PROFICIENT) (see Common reference levels)

11.1.10. ApplyChannel

Provide at least one channel for applications.

Path Type Description Constraints

formUrl

String(255)

An online form where an applicant can apply

Optional (Format: http://www.example.org)

emailAddress

String(50)

An email address where an applicant can send their application

Optional

phoneNumber

String(20)

A phone number where an applicant can call

Optional (Format: +41123456789)

mailAddress

String(255)

A post address where an applicant can send their application

Optional

additionalInfo

String(255)

Currently not used, will be ignored

Optional (do not use)

11.1.11. PublicContact

Provide a public contact if you want to give applicants the opportunity to ask questions about the job. The contact details will be published.

Path Type Description Constraints

salutation

String(3)

Required (MR or MS)

firstName

String(50)

Required

lastName

String(50)

Required

phone

String(20)

Optional (Format: +41123456789) (phone or email must be set)

email

String(50)

Optional (phone or email must be set)

11.1.12. Publication

If the ad falls under the reporting obligation, the ad will be restricted for five business days. After that period, the ad will be published in the Job-Room public area if the publicDisplay flag is set, otherwise not.

Path Type Description Constraints

startDate

String(10)

When does the advertisement publication start

Required (Format: 2018-01-20)

endDate

String(10)

When does the advertisement publication end (max 60 days)

Optional (Format: 2018-01-20)

euresDisplay

Boolean

Should the job ad be displayed in Eures

Required (true or false)

publicDisplay

Boolean

Should the job ad be displayed in Job-Room public area

Required (true or false)

11.2. Request

{
   "externalUrl":"https://jobs.admin.ch/offene-stellen/Bauarbeiter-1234",
   "externalReference":"1234",
   "reportToAvam":false,
   "numberOfJobs":1,
   "contact":{
      "languageIsoCode":"de",
      "salutation":"MR",
      "firstName":"Max",
      "lastName":"Mustermann",
      "phone":"+41311234567",
      "email":"max.mustermann@example.com"
   },
   "jobDescriptions":[
      {
         "languageIsoCode":"de",
         "title":"Bauarbeiter",
         "description":
         "# Anforderungen
         - Zwingende Baustellenkenntnisse im Hoch- und Tiefbau
         - Kenntnisse in den Schalungssystemen Doka, Peri, Meva und Noe
         - Sicherheitsschulung von Vorteil
         - Handwerkliches Geschick

         # Aufgaben
         - Betonieren
         - Ein- und Ausschalen
         - Aufräumen der Baustelle
         - Allgemeine Mithilfe auf Hoch- und Tiefbau Baustellen"
      }
   ],
   "company":{
      "name":"Muster AG",
      "street":"Münsterstrasse",
      "houseNumber":"9",
      "postOfficeBoxNumber":null,
      "postOfficeBoxPostalCode":null,
      "postOfficeBoxCity":null,
      "postalCode":"3007",
      "city":"Bern",
      "countryIsoCode":"CH",
      "website":"https://www.musterag.ch",
      "phone":"+41321234567",
      "email":"info@musterag.ch",
      "surrogate":true
   },
   "employer":{
      "name":"Example company",
      "postalCode":"1200",
      "city":"Geneva",
      "countryIsoCode":"CH"
   },
   "employment":{
      "startDate":"2020-01-20",
      "endDate":null,
      "shortEmployment":false,
      "immediately":false,
      "permanent":true,
      "workloadPercentageMax":100,
      "workloadPercentageMin":100,
      "workForms":[
         "NIGHT_WORK"
      ]
   },
   "location":{
      "remarks":null,
      "postalCode":"3003",
      "city":"Bern",
      "countryIsoCode":"CH"
   },
   "occupation":{
      "avamOccupationCode":"52502",
      "workExperience":"LESS_THAN_1_YEAR",
      "educationCode":"132"
   },
   "languageSkills":[
      {
         "languageIsoCode":"de",
         "spokenLevel":"PROFICIENT",
         "writtenLevel":"INTERMEDIATE"
      }
   ],
   "applyChannel":{
      "mailAddress":null,
      "emailAddress":"bewerbungen@musterag.ch",
      "phoneNumber":"+41311234567",
      "formUrl":null,
      "additionalInfo":null
   },
   "publicContact":{
      "salutation":"MR",
      "firstName":"Max",
      "lastName":"Muster",
      "phone":"+41311234567",
      "email":"max.muster@musterag.ch"
   },
   "publication":{
      "startDate":"2020-01-01",
      "endDate":"2020-02-01",
      "euresDisplay":true,
      "publicDisplay":true
   }
}

11.3. Response

The response provides the id needed to later retrieve the object via Get. The flag reportingObligation indicates whether the ad falls under the reporting obligation, based on the occupation code provided.

{
  "id": "4feae516-d62c-11e9-ab5e-005056ac3479",
  "status": "INSPECTING",
  "sourceSystem": "API",
  "externalReference": "1234",
  "stellennummerEgov": "300002290",
  "stellennummerAvam": null,
  "fingerprint": null,
  "reportingObligation": true,
  "reportingObligationEndDate": null,
  "reportToAvam": false,
  "jobCenterCode": "BEAF0",
  "approvalDate": null,
  "rejectionDate": null,
  "rejectionCode": null,
  "rejectionReason": null,
  "cancellationDate": null,
  "cancellationCode": null,
  "jobContent": {
    "externalUrl": "https://jobs.admin.ch/offene-stellen/Bauarbeiter-1234",
    "numberOfJobs": "1",
    "jobDescriptions": [
      {
        "languageIsoCode": "de",
        "title": "Bauarbeiter",
        "description":
         "# Anforderungen
         - Zwingende Baustellenkenntnisse im Hoch- und Tiefbau
         - Kenntnisse in den Schalungssystemen Doka, Peri, Meva und Noe
         - Sicherheitsschulung von Vorteil
         - Handwerkliches Geschick

         # Aufgaben
         - Betonieren
         - Ein- und Ausschalen
         - Aufräumen der Baustelle
         - Allgemeine Mithilfe auf Hoch- und Tiefbau Baustellen"
      }
    ],
    "company": {
      "name": "Muster AG",
      "street": "Münsterstrasse",
      "houseNumber": "9",
      "postalCode": "3007",
      "city": "Bern",
      "countryIsoCode": "CH",
      "postOfficeBoxNumber": null,
      "postOfficeBoxPostalCode": null,
      "postOfficeBoxCity": null,
      "phone": "+41 32 123 45 67",
      "email": "info@musterag.ch",
      "website": "https://www.musterag.ch",
      "surrogate": true
    },
    "employment": {
      "startDate": "2020-01-20",
      "endDate": null,
      "shortEmployment": false,
      "immediately": false,
      "permanent": true,
      "workloadPercentageMin": "100",
      "workloadPercentageMax": "100",
      "workForms": [
        "NIGHT_WORK"
      ]
    },
    "location": {
      "remarks": null,
      "city": "Bern",
      "postalCode": "3003",
      "communalCode": "351",
      "regionCode": "BE01",
      "cantonCode": "BE",
      "countryIsoCode": "CH",
      "coordinates": null
    },
    "occupations": [
      {
        "avamOccupationCode": "52502",
        "workExperience": "LESS_THAN_1_YEAR",
        "educationCode": "132"
      }
    ],
    "languageSkills": [
      {
        "languageIsoCode": "de",
        "spokenLevel": "PROFICIENT",
        "writtenLevel": "INTERMEDIATE"
      }
    ],
    "applyChannel": {
      "mailAddress": null,
      "emailAddress": "bewerbungen@musterag.ch",
      "phoneNumber": "+41 31 123 45 67",
      "formUrl": null,
      "additionalInfo": null
    },
    "publicContact": {
      "salutation": "MR",
      "firstName": "Max",
      "lastName": "Muster",
      "phone": "+41 31 123 45 67",
      "email": "max.muster@musterag.ch"
    }
  },
  "publication": {
    "startDate": "2020-01-01",
    "endDate": "2020-02-01",
    "euresDisplay": true,
    "euresAnonymous": false,
    "publicDisplay": true,
    "restrictedDisplay": true,
    "companyAnonymous": false
  }
}

11.4. Access token

An access token is returned in the response headers. The token can be used to check the state of jobs under the reporting obligation. The link is built according to the following pattern:

https://www.job-room.ch/manage-job-ads/{id of job-ad}?token={token}

Name

Type

Description

token

String

The access token

11.5. Response status

Code Status Description

201

Created

The job ad has been successfully created

400

Bad Request

The request was malformed or invalid

401

Unauthorized

User is not logged in

403

Forbidden

User has not the required permission to perform this action

12. Get a job advertisement

The Get request returns the state of the data object. The response includes the flag reportingObligation und the date reportingObligationEndDate. This date is only set after approval by the PES (RAV), in case that the ad falls under the reporting obligation.

12.1. Request

Parameter Constraints Default Description

id

Required

The id of the job ad

12.2. Response

{
  "id": "4feae516-d62c-11e9-ab5e-005056ac3479",
  "status": "INSPECTING",
  "sourceSystem": "API",
  "externalReference": "1234",
  "stellennummerEgov": "300002290",
  "stellennummerAvam": null,
  "fingerprint": null,
  "reportingObligation": true,
  "reportingObligationEndDate": null,
  "reportToAvam": false,
  "jobCenterCode": "BEAF0",
  "approvalDate": null,
  "rejectionDate": null,
  "rejectionCode": null,
  "rejectionReason": null,
  "cancellationDate": null,
  "cancellationCode": null,
  "jobContent": {
    "externalUrl": "https://jobs.admin.ch/offene-stellen/Bauarbeiter-1234",
    "numberOfJobs": "1",
    "jobDescriptions": [
      {
        "languageIsoCode": "de",
        "title": "Bauarbeiter",
        "description":
         "# Anforderungen
         - Zwingende Baustellenkenntnisse im Hoch- und Tiefbau
         - Kenntnisse in den Schalungssystemen Doka, Peri, Meva und Noe
         - Sicherheitsschulung von Vorteil
         - Handwerkliches Geschick

         # Aufgaben
         - Betonieren
         - Ein- und Ausschalen
         - Aufräumen der Baustelle
         - Allgemeine Mithilfe auf Hoch- und Tiefbau Baustellen"
      }
    ],
    "company": {
      "name": "Muster AG",
      "street": "Münsterstrasse",
      "houseNumber": "9",
      "postalCode": "3007",
      "city": "Bern",
      "countryIsoCode": "CH",
      "postOfficeBoxNumber": null,
      "postOfficeBoxPostalCode": null,
      "postOfficeBoxCity": null,
      "phone": "+41 32 123 45 67",
      "email": "info@musterag.ch",
      "website": "https://www.musterag.ch",
      "surrogate": true
    },
    "employment": {
      "startDate": "2020-01-20",
      "endDate": null,
      "shortEmployment": false,
      "immediately": false,
      "permanent": true,
      "workloadPercentageMin": "100",
      "workloadPercentageMax": "100",
      "workForms": [
        "NIGHT_WORK"
      ]
    },
    "location": {
      "remarks": null,
      "city": "Bern",
      "postalCode": "3003",
      "communalCode": "351",
      "regionCode": "BE01",
      "cantonCode": "BE",
      "countryIsoCode": "CH",
      "coordinates": null
    },
    "occupations": [
      {
        "avamOccupationCode": "52502",
        "workExperience": "LESS_THAN_1_YEAR",
        "educationCode": "132"
      }
    ],
    "languageSkills": [
      {
        "languageIsoCode": "de",
        "spokenLevel": "PROFICIENT",
        "writtenLevel": "INTERMEDIATE"
      }
    ],
    "applyChannel": {
      "mailAddress": null,
      "emailAddress": "bewerbungen@musterag.ch",
      "phoneNumber": "+41 31 123 45 67",
      "formUrl": null,
      "additionalInfo": null
    },
    "publicContact": {
      "salutation": "MR",
      "firstName": "Max",
      "lastName": "Muster",
      "phone": "+41 31 123 45 67",
      "email": "max.muster@musterag.ch"
    }
  },
  "publication": {
    "startDate": "2020-01-01",
    "endDate": "2020-02-01",
    "euresDisplay": true,
    "euresAnonymous": false,
    "publicDisplay": true,
    "restrictedDisplay": true,
    "companyAnonymous": false
  }
}

12.3. Response status

Code Status Description

200

Ok

The page with job ads has been returned

401

Unauthorized

User is not logged in

403

Forbidden

User has not the required permission to perform this action

404

Not Found

No Job ad has be found for the given id

13. Get all job advertisements belonging to the owner

13.1. Request

Parameter Constraints Default Description

page

Optional

0

The page that should be returned

size

Optional

25

The maximum number of elements on the page

13.2. Response

{
   "content":[
      {
      "id": "4feae516-d62c-11e9-ab5e-005056ac3479",
      "status": "INSPECTING",
      "sourceSystem": "API",
      "externalReference": "1234",
      "stellennummerEgov": "300002290",
      "stellennummerAvam": null,
      "fingerprint": null,
      "reportingObligation": true,
      "reportingObligationEndDate": null,
      "reportToAvam": false,
      "jobCenterCode": "BEAF0",
      "approvalDate": null,
      "rejectionDate": null,
      "rejectionCode": null,
      "rejectionReason": null,
      "cancellationDate": null,
      "cancellationCode": null,
      "jobContent": {
        "externalUrl": "https://jobs.admin.ch/offene-stellen/Bauarbeiter-1234",
        "numberOfJobs": "1",
        "jobDescriptions": [
          {
            "languageIsoCode": "de",
            "title": "Bauarbeiter",
            "description":
             "# Anforderungen
             - Zwingende Baustellenkenntnisse im Hoch- und Tiefbau
             - Kenntnisse in den Schalungssystemen Doka, Peri, Meva und Noe
             - Sicherheitsschulung von Vorteil
             - Handwerkliches Geschick

             # Aufgaben
             - Betonieren
             - Ein- und Ausschalen
             - Aufräumen der Baustelle
             - Allgemeine Mithilfe auf Hoch- und Tiefbau Baustellen"
          }
        ],
        "company": {
          "name": "Muster AG",
          "street": "Münsterstrasse",
          "houseNumber": "9",
          "postalCode": "3007",
          "city": "Bern",
          "countryIsoCode": "CH",
          "postOfficeBoxNumber": null,
          "postOfficeBoxPostalCode": null,
          "postOfficeBoxCity": null,
          "phone": "+41 32 123 45 67",
          "email": "info@musterag.ch",
          "website": "https://www.musterag.ch",
          "surrogate": true
        },
        "employment": {
          "startDate": "2020-01-20",
          "endDate": null,
          "shortEmployment": false,
          "immediately": false,
          "permanent": true,
          "workloadPercentageMin": "100",
          "workloadPercentageMax": "100",
          "workForms": [
            "NIGHT_WORK"
          ]
        },
        "location": {
          "remarks": null,
          "city": "Bern",
          "postalCode": "3003",
          "communalCode": "351",
          "regionCode": "BE01",
          "cantonCode": "BE",
          "countryIsoCode": "CH",
          "coordinates": null
        },
        "occupations": [
          {
            "avamOccupationCode": "52502",
            "workExperience": "LESS_THAN_1_YEAR",
            "educationCode": "132"
          }
        ],
        "languageSkills": [
          {
            "languageIsoCode": "de",
            "spokenLevel": "PROFICIENT",
            "writtenLevel": "INTERMEDIATE"
          }
        ],
        "applyChannel": {
          "mailAddress": null,
          "emailAddress": "bewerbungen@musterag.ch",
          "phoneNumber": "+41 31 123 45 67",
          "formUrl": null,
          "additionalInfo": null
        },
        "publicContact": {
          "salutation": "MR",
          "firstName": "Max",
          "lastName": "Muster",
          "phone": "+41 31 123 45 67",
          "email": "max.muster@musterag.ch"
        }
      },
      "publication": {
        "startDate": "2020-01-01",
        "endDate": "2020-02-01",
        "euresDisplay": true,
        "euresAnonymous": false,
        "publicDisplay": true,
        "restrictedDisplay": true,
        "companyAnonymous": false
      }
    }
   ],
   "currentElements":0,
   "currentPage":0,
   "first":true,
   "last":true,
   "totalElements":0,
   "totalPages":0
}
Name Description

content

The list of job advertisements

currentElements

The number of job advertisements on this page

currentPage

The current page number

first

true if there are no previous pages

last

true if there are no following pages

totalElements

The total number of job advertisements on all pages

totalPages

The total number of pages

13.3. Response status

Code Status Description

200

Ok

The page with job ads has been returned

401

Unauthorized

User is not logged in

403

Forbidden

User has not the required permission to perform this action

14. Filter by status

Get all job advertisements belonging to the owner, filtered by status

14.1. Request

{
    "status": ["INSPECTING", "REJECTED"]
}

The request must indicate one or more valid statuses.

Parameter Constraints Default Description

page

Optional

0

The page that should be returned

size

Optional

25

The maximum number of elements on the page

sort

Optional

DESC

Sort list by updated_time (either ASC or DESC)

14.2. Response

The response structure is identical to the case above, see Response

Name Description

content

The list of job advertisements

currentElements

The number of job advertisements on this page

currentPage

The current page number

first

true if there are no previous pages

last

true if there are no following pages

totalElements

The total number of job advertisements on all pages

totalPages

The total number of pages

14.3. Response status

Code Status Description

200

Ok

The page with job ads has been returned

401

Unauthorized

User is not logged in

403

Forbidden

User has not the required permission to perform this action

15. Update a job advertisement

Update possibility not available at the moment.

16. Cancel a job advertisement

16.1. Request

{
    "code": "OCCUPIED_OTHER"
}
Parameter Constraints Default Description

id

Required

The id of the job ad

code

Required

The cancellation reason code

16.2. Response

No body

16.3. Response status

Code Status Description

204

No Content

The job ad has been successfully updated

400

Bad Request

The request was malformed or invalid

401

Unauthorized

User is not logged in

403

Forbidden

User has not the required permission to perform this action

404

Not Found

No job ad with the given stellennummerEgov was found

Appendix

17. Code lists

17.1. Formats

17.1.1. Dates

The dates are send as string in the ISO 8601 format YYYY-MM-DD

17.1.2. Languages

The languages are sent as string with the ISO 639-1 code (e.g. "de") List of supported languages

17.1.3. Countries

The Countries are sent as string with the ISO 3166-1 alpha-2 (e.g. "ch")

17.1.4. Phone numbers

The phone numbers are sent as string in the format "+41123456789" (Regex "[+][1-9][0-9]{7,18}"). The phone numbers are also validated using the com.google.i18n.phonenumbers.PhoneNumberUtil utility.

17.2. Status of a job advertisement

Value Description

INSPECTING

The job ad has been passed to AVAM system and is waiting for validation

REJECTED

The job ad has been rejected by the public employment agency

PUBLISHED_RESTRICTED

The job ad is approved and is only displayed to registered jobseekers (due to reporting obligation)

PUBLISHED_PUBLIC

The job ad is displayed for everyone

CANCELLED

The job ad has been cancelled

ARCHIVED

The publication reached its end of life and is archived

17.3. Salutations

Value Description

MR

MS

17.4. Work forms

Value Description

SUNDAY_AND_HOLIDAYS

SHIFT_WORK

NIGHT_WORK

HOME_WORK

17.5. Work experience

Value Description

LESS_THAN_1_YEAR

MORE_THAN_1_YEAR

MORE_THAN_3_YEARS

17.6. Spoken and written levels

Value Description

NONE

BASIC

INTERMEDIATE

PROFICIENT

17.7. Cancellation reason codes

Value German English French Italian

OCCUPIED_JOBCENTER

Sie konnten die Stelle besetzen in Zusammenarbeit mit der regionalen Arbeitsvermittlung (RAV)

You were able to fill the position in cooperation with the regional employment centre (RAV)

Vous avez pu pourvoir le poste en collaboration avec l’Office régional de placement (ORP)

Ha potuto assegnare il posto in collaborazione con l’Ufficio regionale di collocamento (URC)

OCCUPIED_AGENCY

Sie konnten die Stelle besetzen in Zusammenarbeit mit der privaten Arbeitsvermittlung (pAV)

You were able to fill the position in cooperation with a private employment agency

Vous avez pu pourvoir le poste en collaboration avec un placeur privé

Ha potuto assegnare il posto in collaborazione con un’agenzia privata di collocamento

OCCUPIED_JOBROOM

Sie konnten die Stelle selber besetzen mit einer Kandidatin/einem Kandidaten aus Job-Room

Your were able to fill the position yourself with a candidate from Job-Room

Vous avez pu pourvoir le poste par vous-même avec un/une candidat/e de Job-Room

Hai potuto assegnare il posto a un candidato di Job-Room

OCCUPIED_OTHER

Sie konnten die Stelle selber besetzen anderweitig

Your were able to fill the position yourself with a candidate not from Job-Room

Vous avez pu pourvoir le poste par vous-même par un autre moyen que Job-Room

Hai potuto assegnare il posto a un’altra persona

NOT_OCCUPIED

Sie konnten die Stelle nicht besetzen

You were unable to fill the position

Vous n’avez pas pu pourvoir le poste

Non ha potuto assegnare il posto

CHANGE_OR_REPOSE

Sie möchten die Ausschreibung ändern oder neu erfassen

You want to change or repost the position

-

-

17.8. AVAM education code

Code German English French Italian

130

Weiterführende Schule (Sek. II

Secondary school (upper-secondary education)

Ecole supérieure (Sec. II)

Scuola superiore (Sec. II)

131

Berufliche Grundbildung EBA oder äquivalent

Vocational education and training with the Swiss Federal VET Certificate or equivalent

Formation professionnelle initiale AFP ou équivalent

Formazione professionale di base CFP o equivalente

132

Berufliche Grundbildung EFZ oder äquivalent

Vocational education and training with the Swiss Federal VET Diploma or equivalent

Formation professionnelle initiale CFC ou équivalent

Formazione professionale di base AFC o equivalente

133

Fachmittelschule oder äquivalent

Upper-secondary specialised school or equivalent

Ecole de culture générale ou équivalent

Scuola specializzata o equivalente

134

Berufsmaturität oder äquivalent

Vocational and professional school-leaving certificate or equivalent

Maturité professionnelle ou équivalent

Maturità professionale o equivalente

135

Fachmaturität oder äquivalent

Specialised school-leaving certificate or equivalent

Maturité spécialisée ou équivalent

Maturità specializzata o equivalente

136

Gymnasiale Maturität oder äquivalent

Baccalaureate school-leaving certificate or equivalent

Maturité gymnasiale ou équivalent

Maturità liceale o equivalente

150

Höhere Berufsbildung, eidg. FA oder äquivalent

Higher professional education and training, Swiss Federal PET diploma or equivalent

Formation professionnelle supérieure BF ou équivalent

Formazione professionale superiore APF o equivalente

160

Höhere Berufsbildung, Diplom oder äquivalent

Higher professional education and training, diploma or equivalent

Formation professionnelle supérieure, diplôme ou équivalent

Formazione professionale superiore, diploma o equivalente

170

Bachelor Fachhochschule oder äquivalent

Bachelor’s degree from a university of applied sciences or equivalent

Bachelor HES ou équivalent

Bachelor SUP o equivalente

171

Bachelor universitäre Hochschule oder äquivalent

Bachelor’s degree from a university or equivalent

Bachelor HEU ou équivalent

Bachelor scuola univ./poli. o equivalente

172

Master Fachhochschule oder äquivalent

Master’s degree from a university of applied sciences or equivalent

Master HES ou équivalent

Master SUP o equivalente

173

Master universitäre Hochschule oder äquivalent

Master’s degree from a university or equivalent

Master HEU ou équivalent

Master scuola univ./poli. o equivalente

180

Doktorat universitäre Hochschule oder äquivalent

Doctorate from a university or equivalent

Doctorat HEU ou équivalent

Dottorato scuola univ./poli. o equivalente

17.9. AVAM occupation code

Refer to separate Excel sheet. The occupation list helps you determine the correct occupation code to provide to the API. The occupation code is required to determine whether a job vacancy falls under the registration requirement.

The revised AVAM occupation list is now available. This list has gone into effect on January 1, 2020. The new Excel sheet includes a mapping from the old to the new occupation codes to help API users prepare for the change.