In this reference we will go over the attributes of the job object and some of the possibilities that you have using the hokify ATS-API.

(For complete documentation, please refer to the Swagger Definition that is auto-generated and up-to-date!)

The "job" object (ICreateOrUpdateJobDTO)

All job data are written via the "job" object (mainly using "params") through the ATS-API.

"sourceId"

The lifespan of a job revolves around the central element: its ID. (hokify-internally known as "sourceId" as it comes from you, or something in your possession: the source of each job.)

We need a unique ID so that we and you in the system can find the jobs again.

• A new job ad on hokify will get created if you createOrUpdateJob with a new sourceId. This sourceId can be anything you want - either any identifier from the software you use, or a simple consecutive number, or a random code you assign to a job. The ID can really be any alphanumerical string. It will only be used internally (meaning not be shown to the end-users) but is also used for identification for job-applications later.

• If you change any detail (for example, the text of the description) but still provide the same sourceId, the job ad will be updated by the createOrUpdateJob call.

• If you would like to unpublish a job, either call a respective endpoint (/job/unpublishJobsWithSourceIds with the sourceId of your job to be unpublished, or /job/unpublishJobsExcludingSourceIds with a list of your desired jobs-to-be-online to unpublish all others).

(Similar to creating any data in any software, these IDs must not be re-used for different jobs at later time!)

"params" (IJobAtsEditFields)

All job data are passed as "params" of type IJobAtsEditFields.

For any individual request, no param is strictly required (as createOrUpdateJob may also be used to simply update a single value).

For a job in general, the minimum details required for a job are the following params (besides its sourceId):

• name: job title for the ad

• address (or some kind of location): for the localization of the jobs (jobs are highlighted in the respective environment of the user). A job without a location can not be published! The simplest form to use is via the address param that can be any string that will be parsed using our location service. You can check the outcome of this via the job preview object that will be mentioned later.

• description or descriptionHTML: the actual job ad text (see details below). Jobs with no description are valid per se, but will have an auto-generated short description text.

• company: the company name (as string) which will be linked to the job.

• isPublished (boolean, default is false): whether to actually have the job published and visible for users. "Published" (isPublished: true) jobs are checked by the server for validity, while "created" only (isPublished: false) jobs might also be incomplete in some parts. Respective error messages and/or warnings will be provided by the createOrUpdateJob API call.

• fields: one or more job fields (= categories) of your job.

• region: the region of the job ("at", "de" or "ch". Use lower case ISO 2-letter country codes for all region/language inputs!). This might be omitted, if a default is set on the server from our side. If in doubt, please contact us.

Additional information that is advisable:

• wage: the salary of the job, to filter for the applicants (also legally required for job ads in Austria)

• type: whether the job is offered as full time, part time, internship or marginal position. (using IDs that can be obtained using GET /job/getJobTypes endpoint. Those IDs will remain the same.)

(All additional information you provide raises job-ad quality and increases the discoverability of your job.)

description / descriptionHTML

The actual description of the job-ad can be submitted either in HTML format (using param descriptionHTML) or plain text (using param description) and will be transformed into the hokify layout. Possible formatting is headings, paragraphs, lists.

About HTML: 

• All headings (h1, h2, h3, h4, h5, h6) are transformed to one level.

• Lists (ul, ol) are displayed as unordered list and flattened to one level only. (Paragraphs starting with "- " (dash followed by space) are treated as lists as well!)

• Paragraphs (p) are kept and displayed with margin in between.

• Newlines (br) are kept and displayed as line-breaks, but with no margin.

• Everything else is removed from the HTML before transforming (especially styling-tags, attributes, links, images, scripts).

About plain-text:

• Lines starting with multiple CAPITAL letters are transformed to headings. (Capitalized text in the middle of a line is kept but not highlighted.)

• Lines starting with dash followed by space ("- ") are treated as lists.

• Line breaks must be line-feed (\n). However, Windows-style (carriage-return line-feed \r\n) works as well since it contains the line-feed anyways.

• Singe line-breaks are just line-breaks (like HTML br) while multiple line-breaks denote paragraphs (like HTML p) with margin in between.

Limitations:

• Other formattings (e.g. Markdown, TeX) are currently not supported. 

• Custom CSS is not supported. 

• Links (e.g. to another job-page / your homepage) are not allowed. (Linking to your homepage is possible on the company-detail page).

The example below shows two different inputs that will result in the same job description in the frontend:

"jobPic"

Submit a job image for each job using the separate "jobPic" when creating or updating a job with createOrUpdateJob.

Encode the image as base64 string to pass it to the endpoint. The image is uploaded to our storage servers and scaled to needed dimensions automatically.

Image requirements:

• resolution: 2000x1300px (orientation: landscape, aspect ratio: 1 / 0.65)

• file size: maximum 10 MB

• file formats: jpeg, jpg, png