Docs  Job Posting  Job posting features  Questionnaires  Custom panel
  • No results found

Custom Questionnaire Panel with GraphQL

The SEEK Questionnaire Panel is built on operations available through our GraphQL endpoint. You can programmatically retrieve recommended questions, define custom questions and privacy policies, and create questionnaires. This allows you to build your own custom user interface for questionnaires.

Before you begin

  • Evaluate whether you can embed the SEEK-built Questionnaire Panel, which is a simpler alternative to creating your own implementation.
  • SEEK recommends using a browser token to manage questionnaires directly from a hirer’s browser. For the browser token to work, you will need to include the mutate:application-questionnaires query:application-library-question-suggestions query:application-questionnaires scope in your request.
  • You can also manage questionnaires from your backend using a partner token.

Recommended questions

The applicationLibraryQuestionSuggestions query returns a list of suggested SEEK library questions based on a partial PositionProfile. This can be used to interactively suggest application questions to a hirer while they’re posting a job ad.
You should invoke the query whenever a hirer updates one of these fields:While only the position’s title, category and location are required, providing position descriptions will increase suggestion relevance.
QueryVariablesResult
CopyGraphQL Explorer
query (
  $positionProfile: ApplicationLibraryQuestionSuggestions_PositionProfileInput!
  $schemeId: String!
  $first: Int
) {
  applicationLibraryQuestionSuggestions(
    schemeId: $schemeId
    positionProfile: $positionProfile
    first: $first
  ) {
    id {
      value
    }
    applicationLibraryQuestion {
      text
      id {
        value
      }
      preferenceSelection {
        typeCode
        message
      }
      responseTypeCode
      responseChoice {
        id {
          value
        }
        text
      }
    }
  }
}
Each suggested applicationLibraryQuestion contains the details of a question from SEEK’s library. A hirer may select up to 8 suggested questions for inclusion in their questionnaire.You should present the hirer with an appropriate input control to record their preferred response choices to each selected question, which drives scoring of questionnaire submissions. The preferenceSelection field describes how you should present the response choice selection.
  • The available typeCodes and corresponding sample implementations are listed below.
  • The message is a description that should be displayed to the hirer to prompt their preference selection.
The following samples provide a visual representation of how you should present the hirer view for each scenario. The accompanying candidate view approximates how the question is presented on SEEK’s Apply Form per the responseTypeCode; it exists for illustrative purposes only and does not need to be shown within your software.

Single choice

SingleChoice indicates that the hirer can select a single preferred response choice. A radio group or dropdown should be used.For a question with a SingleSelect candidate response:
Hirer view
Do you have customer service experience?I will only accept this answer
Candidate view
Do you have customer service experience?

Multi choice

MultiChoice indicates that the hirer can select multiple preferred response choices. A checkbox group should be used.For a question with a SingleSelect candidate response:
Hirer view
Which of the following statements best describes your right to work in Australia?I will accept any of these answers
Candidate view
For a question with a MultiSelect candidate response:
Hirer view
Which of the following Microsoft Office products are you experienced with?I will only accept this combination of answers
Candidate view
Which of the following Microsoft Office products are you experienced with?

Range

Range indicates that the hirer can select two response choices representing the minimum and maximum preferred choices. A set of two dropdowns should be used.For a question with a SingleSelect candidate response:
Hirer view
What is your expected annual base salary?I will accept between this range
to
Candidate view
The minimum dropdown should implement the following rules:
  1. The last option should be disabled
The maximum dropdown should implement the following rules:
  1. The first option should be disabled
  2. The selected minimum and preceding options should be disabled
  3. The selection should be reset if the minimum is greater than or equal to it

Custom questions

If a hirer is unable to find a relevant question from SEEK’s library, they may wish to provide their own question. A hirer may create up to 3 custom questions for inclusion in their questionnaire.We recommend supporting the same question types as the SEEK-built Questionnaire Panel:
  1. Free text
  2. Yes/no
  3. Single select
  4. Multi select
However, you may choose to omit complex selection types if there is limited demand from your hirers.
This is a
free text
questionThe candidate can write a free text response
Component
Copy
[
  {
    "componentTypeCode": "Question",
    "question": {
      "componentTypeCode": "Question",
      "questionHtml": "",
      "responseTypeCode": "FreeText"
    }
  }
]
The above sample generates the corresponding ApplicationQuestionnaireComponentInput to supply to questionnaire creation.

Privacy policy

If your software stores a link to the hirer’s privacy policy, you can present a checkbox that requires candidates to accept the privacy policy as part of the SEEK’s Apply Form. The description and URL of the privacy policy should be populated by your backend, as the hirer shouldn’t need to tailor these details per job ad.
Component
Copy
[]
The above sample generates the corresponding ApplicationQuestionnaireComponentInput to supply to questionnaire creation.

Questionnaire creation

The createApplicationQuestionnaire mutation creates a new questionnaire. You can include SEEK library questions from the applicationLibraryQuestionSuggestions query, custom questions, and a privacy consent component.

For recommended questions

If a library question was suggested via the applicationLibraryQuestionSuggestions query, you should supply its ApplicationLibraryQuestionSuggestion.id as input to the createApplicationQuestionnaire mutation.
MutationVariables
CopyGraphQL Explorer
mutation ($input: CreateApplicationQuestionnaireInput!) {
  createApplicationQuestionnaire(input: $input) {
    applicationQuestionnaire {
      id {
        value
      }
    }
  }
}

For custom questions and privacy policies

MutationVariables
CopyGraphQL Explorer
mutation ($input: CreateApplicationQuestionnaireInput!) {
  createApplicationQuestionnaire(input: $input) {
    applicationQuestionnaire {
      id {
        value
      }
    }
  }
}

Questionnaire retrieval

The applicationQuestionnaire query retrieves a previously created questionnaire by its identifier.
QueryVariablesResult
CopyGraphQL Explorer
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
        }
      }
    }
  }
}
Questionnaires: Panel
Questionnaires: ATS Screening Questions