Receiving Candidate Applications

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 and PUT 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.

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" ]
      }
    }
  },
  "required": [ "candidate", "answers", "media" ]
}

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. The following will be contained in the body text:

  • First & last names
  • Email address
  • Phone number
  • Address (city-level resolution)
  • Questions and answers
  • Associated job title and client reference
  • CV, cover letter, and intro video attachments as links