Questionnaires

Questionnaires

A job ad may specify a questionnaire to include in SEEK’s native apply form. Candidates complete the questionnaire as part of their job application, and their responses are made available through the Application Export use case. Questionnaires are rendered on SEEK’s candidate website and in our mobile apps.
The SEEK API assumes that your software already has a mechanism for creating and managing custom questions. The create mutation lets you create questionnaires in the structure expected by the SEEK API and returns an ID that can be specified when posting a job ad.

Immutability

For an equitable screening process, a SEEK job ad presents the same questionnaire to all applicants. This is enforced in two ways:
  1. The ApplicationQuestionnaire object is immutable.
    If your software supports mutable questionnaires, you may snapshot its latest state by creating a new ApplicationQuestionnaire at time of posting.
  2. To avoid confusion, your software’s frontend should not allow hirers to modify a live job ad’s questionnaire.

Data structure

An ApplicationQuestionnaire is represented as an immutable collection of components.
  • ApplicationPrivacyConsent allows the hirer to link to a privacy policy for candidates to consent to.
  • ApplicationQuestion allows the hirer to ask a screening question:
    • FreeText presents the candidate with a free text input labelled with the question’s questionHtml. They must input at least one character before submitting their application.
    • SingleSelect presents the candidate with a set of mutually exclusive choices. They must select a single choice before submitting their application.
      SEEK renders these questions either as radio buttons or a dropdown list, depending on the number of choices.
    • MultiSelect presents the candidate with a set of non-exclusive choices. They must select at least one choice before submitting their application.
      SEEK renders these questions as a list of checkboxes.
You can explore these components through our interactive questionnaire builder.

Questionnaire submission association

A candidate’s questionnaire submission can be retrieved through the Application Export use case. The submission can be correlated back to the presented questionnaire and to its individual components.
If you manage questionnaires as a holistic collection in your software, retrieve questionnaire.id to correlate the submission back to the questionnaire ID.
If you manage individual questionnaire components in your software, supply a unique reference value for each ApplicationQuestionnaireComponent during questionnaire creation. You can then retrieve responses.*.component.value from the submission to correlate each response back to its corresponding component.

Preferred choices & scoring

The SEEK API can optionally calculate a numeric score for each questionnaire submission. This requires that your software indicates which response choices are preferred by the hirer. The calculated score and preference indicators are not otherwise used by SEEK.
Each SingleSelect and MultiSelect ApplicationQuestion specifies a collection of possible choices through the responseChoice field. An ApplicationQuestionChoice can be preferenced by setting its preferredIndicator during questionnaire creation. Candidate responses are scored against these preferred choices.
These scores are provided as an advisory screening indicator for the hirer. All candidate applications will be delivered to your software; SEEK does not support knockout questions and does not reject applications based on score.

Limits

The SEEK API imposes the following limits on questionnaires:
Lengthy application forms deter candidates from applying, so we encourage hirers to keep their questionnaires short and focussed. As a point of reference, SEEK’s native job posting experience recommends a maximum of five questions.

Operations

Create an application questionnaire

The createApplicationQuestionnaire mutation creates a new questionnaire.
MutationVariables
mutation ($input: CreateApplicationQuestionnaireInput!) {
  createApplicationQuestionnaire(input: $input) {
    applicationQuestionnaire {
      id {
        value
      }
    }
  }
}
For detailed information on all available fields, refer to the CreateApplicationQuestionnaireInput schema definition.

Retrieve an application questionnaire

The applicationQuestionnaire query retrieves a previously created questionnaire by its identifier.
QueryVariablesResult
query ($id: String!) {
  applicationQuestionnaire(id: $id) {
    id {
      value
    }
    components {
      id {
        value
      }
      componentTypeCode
      ... on ApplicationQuestion {
        questionHtml
        responseTypeCode
        value
        responseChoice {
          text
          value
        }
      }
      ... on ApplicationPrivacyConsent {
        descriptionHtml
        privacyPolicyUrl {
          url
        }
      }
    }
  }
}