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 you want to insert the Questionnaire Panel:
HTML
Copy
<script
  type="text/javascript"
  src="https://seekcdn.com/hirer/indirect-posting/questionnaire-panel/SEEKQuestionnairePanel.js"
></script>

Step 2: Render the panel

The render method renders an instance of the panel in the specified DOM element.
The render method 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 call render to refresh question suggestions.
The render function may throw errors if:
  • The containerNode provided is not a valid HTMLElement
  • The options you provide are incorrect

Example JavaScript

JavaScript
Copy
SEEKQuestionnairePanel.render(containerNode, options);
  • containerNode – (DOM Node) The DOM element to render the panel into.
  • options – Options for rendering the panel; see options below.

Options

Option property
Type
Description
getAuthToken
() => Promise<string>
Function to call to retrieve the browser token to use when calling the SEEK API.
errorHandler
({ errors: object[] }) => void
optional
You may provide your own errorHandler in order to monitor errors being generated by hirers as they use the Questionnaire Panel. If nothing is provided, errors are printed with console.error.
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.
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.
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.
ErrorResult
The errorHandler configured in the options is provided with an array of ErrorResult objects when something goes wrong with the Questionnaire Panel. The information is generally not useful to hirers, as the panel itself will show the hirer a message for any problems they can fix themselves.
ErrorResult property
Type
Description
errorCode
string
One of the SEEK API’s error responses.
message
string
A description of what the problem is.
ErrorResult examples
INTERNAL_SERVER_ERRORBAD_USER_INPUTUNAUTHENTICATEDFORBIDDEN
Copy
{
  "errorCode": "INTERNAL_SERVER_ERROR",
  "message": "[Network error]: TypeError: Network request failed"
}

Sample code

JavaScript
Copy
try {
  SEEKQuestionnairePanel.render(
    document.getElementById('seekQuestionnaireContainerDiv'),
    {
      // 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');
      },
      // You may provide an errorHandler to log any errors that occur with the Questionnaire Panel.
      errorHandler: ({ errors }) => {
        logErrors(errors);
      },
      // 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 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.
  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 SEEKQuestionnairePanel.save(). It returns a Promise to a result object. SEEKQuestionnairePanel.save() does not throw exceptions.

Result object

Result property
Type
Description
errorCode
string | null
If an error has occurred, a code is returned indicating the nature of the problem. One of BAD_USER_INPUT, INTERNAL_SERVER_ERROR, UNAUTHENTICATED, or FORBIDDEN.
data
object | null
An object that contains information about the saved questionnaire.
Only present when questions were configured in the panel and errorCode is null.
data.id
string
The questionnaire ID of the saved questionnaire. For example, seekAnzPublicTest:applicationQuestionnaire:rrv2:SqFmkV8S2dMipyqbHjD9Mr.
If the save succeeded, then errorCode will be null, 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 errorCode will be null, 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 the errorCode will be BAD_USER_INPUT, and data will be null. You should not continue to post the job ad, as the hirer intends to add a questionnaire but has made a correctable error.
If the token the panel receives from the configured getAuthToken option is expired or invalid, then errorCode will be UNAUTHENTICATED. If the token was issued to a different hirer than what is included in positionProfile.positionOrganizations, then errorCode will be FORBIDDEN. For all other errors, including network connectivity issues, the errorCode will be INTERNAL_SERVER_ERROR.
In all these error scenarios, data will be null. You should not continue to post the job ad, as the hirer has intended to add a questionnaire, but there has been a fatal error.
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 SEEKQuestionnairePanel.save();


  if (result.errorCode) {
    // Do not post the job ad if an error occurs while saving the questionnaire.
    // The panel will display an 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 SEEKQuestionnairePanel.save(), and if there is a returned questionnaire ID and no errorCode, then continue to save the draft, persisting the new questionnaire ID returned. To load the draft into the Questionnaire Panel, you must provide the saved questionnaireId and set the mode to Create in the panel options.
Archived: Questionnaires (V1)
Use cases: Optimised Apply