Questionnaire Panel

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.

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
stringoptional
The ID of an existing questionnaire to load into the panel. Questionnaires are immutable; once saved they cannot be edited.
locale
stringoptional
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
objectoptional
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
stringoptional
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
stringoptional
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

  1. The panel loads and invokes the getAuthToken function passed to it.
  2. 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.
  3. Your backend authenticates and authorizes the user.Your software is responsible for verifying that the user is authorized 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.
  4. 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.
  5. Your backend responds with the browser token.
  6. Your frontend returns the browser token from the getAuthToken function.
  7. 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.

Troubleshooting

See our general panel troubleshooting documentation for more information.
Job posting features: Questionnaires
Questionnaires: ATS Screening Questions