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. This provides identifiers for images and videos that will be included with job creation and update requests. |
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 the descriptions for display and the IDs that will be used in the API. |
Additional Compensations | A default list of extra compensations. These values are merely common suggestions; custom values are supported when creating and updating a job listing. |
Question Templates | A default list of screening questions. These templates aren't required; custom questions are supported. These are merely the ones that are recommended to you when you create a job listing online. |
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.
At this time, management of the media library must be performed on ZEIL.com. The API does not expose this functionality.
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. Ideally this will be the active user in the ATS. It's not expected that this will be a user-provided value.
If the email address is not associated with an existing user on ZEIL.com, a new user account will be created and added to the organisation as an admin. An invitation email containing a 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.
Automatic Publication
By default, job listings will automatically publish as soon as the required information has been supplied (assuming the organisation has sufficient credits or a subscription in place). 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.
Job listings are 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