Questionnaire Panel

    Suggestions will appear below the field as you type

    Questionnaire Panel

      Suggestions will appear below the field as you type

      Questionnaire Panel

      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.
      • propsProps 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
      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

      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 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.