Questionnaire Panel | SEEK Developer

SEEK provides a Questionnaire Panel you can embed within your job posting flow. The Questionnaire Panel allows hirers to interactively create questionnaires for candidates to complete as part of their job application. It lets hirers:

Select relevant question suggestions from SEEK’s library of commonly used questions to ask candidates as a part of their job application.
The relevancy of the questions to the hirers’ role will depend on the position’s title, job category, location, advertisement details, search summary, and search bullet points that are inputted.
Add custom questions if they do not find the suggestions from SEEK’s library to be relevant.
Select preferred answers for each question.
Attach a company privacy policy if applicable.

Browser support

The Questionnaire Panel tracks our standard browser support policy.

Step 1: Include the panel

Add the following script tag to the page where the Questionnaire Panel will be displayed:

HTML

Copy

<script

  type="text/javascript"

  src="https://integration.seek.com/panels/SeekApi.js"

></script>

Step 2: Render the panel

The SeekApi.render function renders an instance of the panel in the specified DOM element.

The render function must be called on page load and whenever the properties of the positionProfile object change. For example, if the hirer updates their position title you must re-render the panel to refresh question suggestions.

The render function may throw errors if:

The containerNode provided is not a valid HTMLElement

JavaScript

Copy

const { dispatchEvent } = SeekApi.render(containerNode, 'questionnaire', props);

containerNode – (DOM Node) The DOM element to render the panel into.
'questionnaire' - The name of the panel to render.
props – Props for rendering the panel.

Modifying the containerNode or its children after the render function has been called may lead to unexpected behaviour.

Props

Prop	Type	Description
`getAuthToken`	`() => Promise<string>`	Function to call to retrieve the browser token to use when calling the SEEK API.
`schemeId`	`string`	The scheme ID to use when suggesting questions or creating questionnaires. Either `seekAnz` or `seekAnzPublicTest`.
`mode`	`string`	The mode of the panel. Set to `Create` when posting a new job ad, and `Update` when updating an existing job ad. The widget will show a non-editable summary of the questionnaire in update mode.
`questionnaireId`	`string` optional	The ID of an existing questionnaire to load into the panel. Questionnaires are immutable; once saved they cannot be edited.
`locale`	`string` optional	Specifies the locale to display content in e.g., `en-AU`. Set this prop to override the default localisation behaviour based on users browser preferences. Supported locales are outlined in the content localisation documentation.
`privacyPolicy`	`object` optional	The configuration options for the hirer’s privacy policy. The option to include a privacy policy question will only be presented to the hirer if this is present.
`privacyPolicy.url`	`string`	The website where the hirer’s privacy policy is hosted. This should start with `http://` or `https://`.
`privacyPolicy.descriptionHtml`	`string` optional	A short phrase to present to candidates to prompt them to accept the privacy policy. Defaults to “Do you agree to the privacy policy?”
`positionProfile`	`object`	The configuration options for providing information about the position being posted. This information is used to suggest questions relevant to the position.
`positionProfile.jobCategories`	`string[]` optional	The array of identifiers for the position’s job category. Only a single value is currently accepted.
`positionProfile.positionLocation`	`string[]` optional	The array of identifiers for the position’s location. Only a single value is currently accepted.
`positionProfile.positionOrganizations`	`string[]`	The array of identifiers of the hirer posting the job. Only a single value is currently accepted.
`positionProfile.positionTitle`	`string` optional	The title of the position.
`positionProfile.positionFormattedDescriptions`	`object[]` optional	An array of formatted position profile descriptions.
`positionProfile.positionFormattedDescriptions[].content`	`string`	The HTML content of the description.
`positionProfile.positionFormattedDescriptions[].descriptionId`	`string`	The description type. One of `AdvertisementDetails`, `SearchBulletPoint`, or `SearchSummary`.

Sample code

JavaScript

Copy

try {

  const { dispatchEvent } = SeekApi.render(

    document.getElementById('seekQuestionnaireContainerDiv'),

    'questionnaire',

      // Function to call to retrieve the browser token to use when calling the

      // SEEK API, see "Step 3" for more details.

      getAuthToken: () => {

        return Promise.resolve('browser token');

},

      // The schemeId controls whether the panel talks to the live production

      // environment or the Playground environment.

      schemeId: 'seekAnzPublicTest',

      // The mode controls whether the panel allows edits to the questionnaire.

      // Questionnaires are immutable, and cannot be added to or removed from a

      // posted job ad.

      mode: 'Create',

      // Providing a questionnaire ID will make the panel load the data from that

      // questionnaire. If the questionnaire was saved as part of a draft job

      // ad and the mode is still `Create`, the widget will allow the hirer to

      // add and remove questions.

      questionnaireId:

        'seekAnzPublicTest:applicationQuestionnaire:rrv2:SqFmkV8S2dMipyqbHjD9Mr',

      // The privacy policy allows you to configure how a hirer‘s privacy policy

      // may be attached.

      privacyPolicy: {

        url: 'https://example.com/privacy-policy.html',

        descriptionHtml: 'Do you accept the terms in the privacy policy?'

},

      // The positionProfile allows you to add the details of the position being

      // posted to improve question suggestions.

      positionProfile: {

        jobCategories: 'seekAnzPublicTest:jobCategory:seek:27HXTkNXh',

        positionLocation: 'seekAnzPublicTest:location:seek:W7NggeKH',

        positionOrganizations: 'seekAnzPublicTest:organization:seek:E2LikAHu',

        positionTitle: 'Office Manager',

        positionFormattedDescriptions: [

            content:

              '<strong>Amazing opportunity!</strong><p>Do you want to join a fast-paced company, managing the office and staff?</p>',

            descriptionId: 'AdvertisementDetails'

},

            content: 'Great culture',

            descriptionId: 'SearchBulletPoint'

},

            content: 'Exciting role fronting a dynamic office',

            descriptionId: 'SearchSummary'

);

} catch (error) {

  // Errors thrown here might be caused by not providing a valid HTMLElement as

  // the containerNode, a configuration error in your options, or by the

  // Questionnaire Panel script not successfully loading.

Step 3: Handle browser token requests

The panel loads and invokes the getAuthToken function passed to it.
Your frontend requests a browser token from your backend.
The getAuthToken function should request a new token for the hirer ID in positionProfile.positionOrganizations. If a user switches to a different SEEK hirer account in your posting form, your software should re-render the panel with the new hirer ID in positionProfile.positionOrganizations, and ensure that subsequent invocations of getAuthToken will request a token for the new hirer ID.
Your backend authenticates and authorises the user.
Your software is responsible for verifying that the user is authorised to access a given hirer ID. A user must not be able to request a browser token for an arbitrary organization that they do not belong to.
Your backend requests a browser token from the SEEK API for the appropriate hirer ID and mutate:application-questionnaires query:application-library-question-suggestions query:application-questionnaires query:organizations scope.
Your backend responds with the browser token.
Your frontend returns the browser token from the getAuthToken function.
The panel can now make requests to the GraphQL endpoint.

HTTP

Copy

POST https://graphql.seek.com/auth/token HTTP/1.1

Authorization: Bearer PARTNER_TOKEN_HERE

Content-Type: application/json

User-Agent: YourPartnerService/1.2.3

  "hirerId": "seekAnzPublicTest:organization:seek:93WyyF1h",

  "scope": "mutate:application-questionnaires query:application-library-question-suggestions query:application-questionnaires query:organizations",

  "userId": "317665"

Step 4: Post the job ad

When the hirer is ready to post their job ad, your software should call dispatchEvent('seek:questionnaire:save'). It returns a Promise to a result object. dispatchEvent('seek:questionnaire:save') does not throw exceptions.

Result object

Result property	Type	Description
`isError`	`boolean`	Whether an error has occurred.
`data`	`object` \| `null`	An object that contains information about the saved questionnaire. Only present when questions were configured in the panel and `isError` is `false`.
`data.id`	`string`	The questionnaire ID of the saved questionnaire. For example, `seekAnzPublicTest:applicationQuestionnaire:rrv2:SqFmkV8S2dMipyqbHjD9Mr`.

If the save succeeded, then isError will be false, and data.id will contain the saved questionnaire’s ID. You may provide the new questionnaire ID in the PostPosition_PositionProfileInput.seekApplicationQuestionnaireId and PostPositionProfileForOpeningPositionProfileInput.seekApplicationQuestionnaireId mutation inputs, or persist it as part of a draft job ad.

If the hirer did not add any questions via the panel, then isError will be false, and data will be null. You should continue to post the job ad without a questionnaire ID.

If there was some problem with the questions the hirer added—for example, adding a custom question, but not configuring any answers—then isError will be true, and data will be null. You should not continue to post the job ad, as the hirer intends to add a questionnaire but an error has occurred.

JavaScript

Copy

const postSeekJobAd = async (input) => {

  // Call a posting mutation to post or update a SEEK job ad.

};

const handleSubmitButton = async () => {

  const input = {

    // Compose from form data.

};

  const result = await dispatchEvent('seek:questionnaire:save');

  if (result.isError) {

    // Do not post the job ad if an error occurs while saving the questionnaire.

    // The panel will display an actionable error message to the hirer.

    return;

  // Data will be nullish if the hirer did not add any questions via the panel.

  if (result.data?.id) {

    input.positionProfile.seekApplicationQuestionnaireId = result.data.id;

  await postSeekJobAd(input);

};

Draft job ads

If your software supports draft job ads, you should also save the questionnaire state as part of the draft. Saving a questionnaire for a draft works the same way as saving for posting a job ad. Call dispatchEvent('seek:questionnaire:save'), and if there is a returned questionnaire ID and isError is false, continue to save the draft and persist the ID. To load the draft into the Questionnaire Panel, you must provide the saved questionnaireId and set the mode to Create in the panel options.

Job posting features: Questionnaires

Questionnaires: ATS Screening Questions