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
Before you can build a job listing, you'll need some common details that cannot be expressed in the OpenAPI Description as well as the organisation's media library. The media library defines a set 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 uploaded directly to the library 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. As a result, it will receive a new ID. We recognise that this can cause confusion, and we 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.
GET /api/integration/jobs
Returns a paged list of job listings.
Query Parameter | Description |
|---|---|
| 0-based index of the page to return. Default is 0. |
| Selects which stage of jobs to return. Can be |
GET /api/integration/job/{job-id}
Returns details for a job listing.
POST /api/integration/jobs
The title and userEmail properties are required.
The userEmail property indicates the user which will own this job listing going forward. This is displayed in ZEIL as the hiring manager. It is expected that this email will be that of the current user of the ATS software. This should not be a configurable value.
If the email address is not associated with an existing ZEIL 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.
Returns a JSON object with the job listing's ID and a stage.
DRAFTindicates that the job listing is still in-progress.PUBLISHEDindicates that the job listing has been submitted to the publication process.
PUT /api/integration/job/{job-id}
The PUT endpoint operates on the payload using a JSON merge, in that only those fields set in the payload will be updated. For updates, we advise only sending fields that need to change rather than re-sending the entire payload.
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 listing 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
Returns a JSON object with the job listing's ID and a stage.
DRAFTindicates that the job listing is still in-progress.PUBLISHEDindicates that the job listing has been submitted to the publication process.
DELETE /api/integration/job/{job-id}
Unpublishes a published job listing or deletes a draft job listing.
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. The automatic moderation process may take up to five minutes, so there may be a delay between receiving a PUBLISHED response and the job appearing in search results.