Managing Job Listings
The API is designed to facilitate three basic operations:
- fetching general job listing information
- managing job listings
- receiving candidate applications
You can interact with the integrations API at https://zeil.com/api/index.html.
The OpenAPI Description (v3.0.1) can be found at https://zeil.com/api/integrations-api/openapi.yaml. (JSON format is also available.)
Fetching General Job Listing Information
In order to build job listings, you'll need some details that are common to all job listings but cannot be expressed in the OpenAPI Description. In addition, each organisation defines a media library of images and videos that can be set on the job listing.
These details can be obtained using the following endpoints:
Endpoint | Description |
|---|---|
| Lists common job listing data. As this information is not likely to change, we recommend that it be cached. |
| Lists an organisation's media library. |
Jobs Metadata
This endpoint lists data that is common across all job listings but cannot be expressed in the OpenAPI Description. The information retrievable via this endpoint includes:
Data | Description |
|---|---|
Industries | The list of industries, including both descriptions (for display) and IDs that will be used in the API. |
Additional Compensations | A default list of extra compensations |
Question Templates | A default list of screening questions |
The additional compensations and question templates are suggestions only. The API does accept custom values for these.
Organisation Media
This endpoint lists the card (portrait orientation) and tile (landscape orientation) images as well as the videos from the organisation's media library. The library consists of media used in previous job postings or explicitly uploaded on ZEIL.com
Every media library entry reported through this endpoint will have a URL (so that the media can be displayed, if desired) as well as an ID to be used in the API.
When posting a job, the media identified by this endpoint is copied into the job. Thus, it will receive a new ID. We recognise that this is confusing and are working toward a solution.
Creating & Managing Job Listings
Job listing management is exposed via a set of basic CRUD operations:
Endpoint | Description |
|---|---|
| Lists an organisation's job listings. |
| Returns a single job listing. |
| Creates a new job listing. |
| Updates a job listing. |
| Closes a job listing. |
The POST and PUT endpoints accept application/json payloads, and all returns will also be application/json.
For the POST endpoint, title and userEmail are required. The userEmail field indicates the user which will own this job listing going forward.
If the email address is not associated with an existing user, a new user account will be created and added to the organisation as an admin. An invitation email containing an temporary password will also be sent to allow the new user to claim their new ZEIL account.
The PUT endpoint operates on the payload using a JSON merge, in that only those fields set in the payload will be updated.
The API does not distinguish between a missing property and the property being set with null. As such, there is currently not a way to remove a set value without replacing it with a new value.
A job is still editable after publication, however, attempting to edit any of these fields for a published job will return a 400 Bad Request status code:
locationquestionscardImagestileImagevideo
Automatic Publication & Content Moderation
By default, job listings will automatically publish as soon as the required information has been supplied (assuming the organisation has sufficient credits). The following fields comprise this minimum dataset:
titledescriptionlocationroleLevelworkTypesworkPlaceindustriescompensationcardImagestileImage
Automatic publication can be overridden by setting the retainAsDraft property to true. This property is not saved and must be set on every call for which you wish to prevent automatic publication. This has a side effect where a draft job listing which has all required information can be published as-is by sending an empty JSON object payload to PUT /api/integration/job/{job-id}.
The POST /api/integration/jobs and PUT /api/integration/job/{job-id} response objects will indicate the job status.
The text found in the title and description fields will be automatically moderated by our systems upon publication. This may take up to five minutes, so there may be a delay between receiving a "published" response and the job appearing in search results.