Receiving Candidate Applications

The API offers two methods for informing clients that a candidate has submitted an application:

Webhooks
Email submission

Note

If neither of these solutions satisfy your needs, please contact the ZEIL sales team to discuss options for engineering a custom solution.

Both the POST /jobs and PUT /jobs/{id} endpoints support a clientData property, which is a JSON object that can accept arbitrary data. This property is used to provide any client-specific information required for receiving applications.

Currently, integrations can only support one of these notification methods at a time, and applies to all jobs. This information needs to be configured during the integration setup.

Webhooks

For webhook integrations, the callback URL will need to be provided in clientData under the callbackUrl property.

To allow verification that the request is from ZEIL, the Z-Client-Id header will contain your OAuth Client ID.

The payload will carry candidate information along with any file attachments. The request payload is application/json using the following JSON Schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://zeil.com/api/schemas/application-callback",
  "type": "object",
  "properties": {
    "candidate": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" },
        "lastName": { "type": "string" },
        "email": {
          "type": "string",
          "format": "email"
        },
        "phone": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "suburb": { "type": "string" },
            "city": { "type": "string" },
            "postCode": { "type": "string" }
          },
          "minProperties": 1
        }
      },
      "required": [ "firstName", "lastName", "email" ]
    },
    "media": {
      "type": "object",
      "properties": {
        "resumeUrl": {
          "type": "string",
          "format": "uri"
        },
        "coverLetterUrl": {
          "type": "string",
          "format": "uri"
        },
        "introVideoUrl": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": [ "resumeUrl" ]
    },
    "workHistory": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "companyName": { "type": "string" },
          "roleTitle": { "type": "string" },
          "description": { "type": "string" },
          "startDate": {
            "type": "string",
            "format": "date"
          },
          "endDate": {
            "type": "string",
            "format": "date"
          }
        },
        "required": ["companyName", "roleTitle", "description", "startDate"]
      }
    },
    "answers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "question": { "type": "string" },
          "answers": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": [ "question", "answers" ]
      }
    },
    "job": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "clientRef": { "type": "string" },
        "postUrl": { "type": "string" }
      },
      "required": [ "title" ]
    }
  },
  "required": [ "candidate", "answers", "workHistory", "media", "job" ]
}

Email Submission

For email integrations, the target email address will need to be provided in the clientData under the submissionEmail property. The email will include the candidate's CV as an attachment.

You will be provided with the relevant organisation IDs when setting up.