Option 2: GraphQL

Your custom user interface must be rebuilt on our new advertisementProducts query, which should be simpler to maintain over time and more flexible.Note the following high-level differences compared to the legacy ANZ-specific queries:
  1. A single query serves both creating and updating a job ad.This is similar to how we provide one SEEK-hosted panel to serve both scenarios.The query must be called on page load and whenever the properties of the positionProfile input change. For example, if the hirer selects a new location, you must re-render the panel to reflect updated products and pricing.When creating a job ad, your software must omit the optional profileId field. When updating a job ad, your software must provide its profileId.
  1. A variable number of ad products may be returned.Previously, the ANZ-specific queries would always return 3 ad products. Now, your interface must be capable of displaying a variable number of ad products, typically between 1 and 4. If there is a hard limit to the number of ad products that you can display, you must provide a limit to the query so that SEEK can provide the most relevant set of products within your constraints. Do not manually truncate the returned list as that may exclude highly relevant products.
  2. A variable set of ad products may be returned.Previously, the ANZ-specific queries would always return Classic, StandOut and Premium. Your software must not hardcode any logic based on specific ad product names or identifiers. The names and identifiers of ad products may vary without warning, so hardcoding them could cause your integration to break and prevent hirers from posting job ads.
  3. The data structure includes the AdvertisementProduct.features supported by each product.Your software must conditionally display brand selection and search bullet point inputs based on these dynamic feature indicators. You may have a similar capability if you integrated with the feature indicators of the previous Ad Selection queries, but we now provide parameters that detail which brand components and how many bullet points are supported:
    AdvertisementProduct
    Copy
    {
      "features": {
    -   "brandingIndicator": true,
    +   "branding": {
    +     "coverImageIndicator": false,
    +     "logoIndicator": true
    +   },
    -   "searchBulletPointsIndicator": true,
    +   "searchBulletPoints": {
    +     "limit": 3
    +   }
      },
      // ...
    };
  4. The data structure and associated business logic should be simpler.Previously, the ANZ-specific queries had a complex data structure and display rules. The new AdvertisementProduct object has a smaller selection of fields that can be directly mapped to your user interface.The ANZ-specific queries returned a price.visibleForHirerIndicator field which your software had to read to determine whether to display the price. Now, the new query internally handles price visibility. Your software should display the products[].price.summary if it is populated, and hide the field if the price is null.
Review the user experience guide to better understand these new requirements.

Managing variable job ads

Due to the variable nature of SEEK’s product ladder, the new panel and GraphQL query return ephemeral product IDs that reference the set of products quoted at that point in time. When a hirer selects a product and your software propagates its identifier to post or update a job ad, SEEK will scan recent ad selection contexts for a match and attempt to lock in the exact quoted product features and pricing.Ad products presented to a hirer are only valid within the context of the workflow that they were executing at the time. Product IDs cannot be persisted long term; they should not be stored alongside a posted job ad for subsequent update workflows or to otherwise build a hardcoded mapping.The selected product ID may be temporarily stored in a job ad draft. When the hirer resumes their posting workflow from the draft at a later date, this previous product ID should not be directly used to post the job ad. Instead, pass the previous product ID to ad selection as the selectedAdvertisementProductId. Ad selection will then pre-select an equivalent ad product and return new product IDs that can be used to post the job ad.

Posting a job ad

Your software must omit the deprecated seekAnzAdvertisementType field in favour of a seekAdvertisementProductId sourced from our new panel or GraphQL query. Your software should always omit unused arguments as a best practice to reduce the surface area of your integration. Setting seekAnzAdvertisementType will result in failed Job Posting create and update calls following the December 2024 retirement date.
BeforeAfter (correct)After (incorrect)
Copy
{
  "postingInstructions": {
    "seekAnzAdvertisementType": "Classic"
  }
}
See the relevant use case documentation for more information.

Querying a job ad

If your software retrieves the current state of a job ad from the SEEK API, it must omit the deprecated seekAnzAdvertisementType field in favour of the new seekAdvertisementProduct field. Your software should only select the fields it uses as a best practice to reduce the surface area of your integration. Selecting seekAnzAdvertisementType will result in failed Job Posting queries following the December 2024 retirement date.
BeforeAfter (correct)After (incorrect)
CopyGraphQL Explorer
# Inline arguments are only used to simplify these examples.
# Parameterise your production queries with variables.
# https://developer.seek.com/graphql/in-practice#variables


query {
  positionProfile(id: "seekAnzPublicTest:positionProfile:jobAd:2782PZfXV") {
    postingInstructions {
      seekAnzAdvertisementType
    }
  }
}

Updating a job ad

In a typical update workflow, you should present an ad selection interface to the hirer so they can choose to upgrade their ad product.Your software must omit the deprecated seekAnzAdvertisementType field in favour of a seekAdvertisementProductId sourced from our new panel or GraphQL query. Using seekAnzAdvertisementType will result in failed Job Posting create and update calls following the December 2024 retirement date.Under certain circumstances, it may be infeasible to present an ad selection interface to the hirer when an update is made. For example, the update may be driven by a back-end process in your software rather than an individual user interacting with an update workflow. In such scenarios, you should omit both seekAdvertisementProductId and seekAnzAdvertisementType to retain the current ad product.See the relevant use case documentation for more information.

Exit criteria

The following criteria need to be met before progressing to the next feature:
Criteria
Description
Ad selection built
SEEK hirers can select available SEEK ad products and see pricing when creating or editing a job ad in your software
Ad selection re-render implemented
SEEK hirers can see new products when the position location, job category or title has changed
Ad selection fallback removed
SEEK hirers must not see a dropdown list of hardcoded ad types when the Ad Selection Panel fails to load
User experience signed off
SEEK has signed off on your ad selection user experience
Job ad posted successfully
Hirer can successfully post a job ad to SEEK with their selected ad product
Job ad updated successfully
Hirer can successfully update a job ad to SEEK with their selected ad product
Ad selection: Option 1: Panel
Option 2: GraphQL: User experience guide