Ad selection with GraphQL

Available ad products can be programmatically retrieved by your software when posting or updating a job ad. This allows you to build your own custom user interface for ad selection.

Before you begin

  • Evaluate whether you can embed the SEEK-built Ad Selection Panel, which is a simpler alternative to creating your own implementation.
  • SEEK recommends using a browser token to query ad products directly from a hirer’s browser. For the browser token to work, you will need to include the query:ad-products scope in your request.
  • You can also query ad products from your backend using a partner token.

Building a custom Ad Selection Panel

If embedding the SEEK-built Ad Selection Panel is not applicable in your software, you can create your own implementation using the below GraphQL queries.Your custom Ad Selection Panel will need to retrieve ad products, map and display fields from the query responses and support varying pricing scenarios.

Operations

The SEEK API provides three queries for retrieving ad products:The above queries must be executed on page load and whenever the properties of the draftAdvertisement input change:These fields affect the price of the job ad. You must re-render the panel to reflect updated pricing.

Pricing scenarios

Prices for SEEK ad products should be displayed to hirers in different ways depending on if they have an ad budget  contract with SEEK.Each scenario includes an image with mapping numbers describing how the SEEK built Ad Selection Panel displays information. These numbers correspond to explanations in the field mapping section.You can test the queries within each scenario in the Playground.

New job ad with SEEK contract

This is the default scenario for querying ad products for a new job ad in the Playground environment.This pricing scenario assumes the hirer has a SEEK ad budget contract set up for all available ad products, and has selected the Classic ad product.
SEEK Contract - Create
See field mapping for details on how the GraphQL response must be mapped to your panel.
QueryVariablesResult
CopyGraphQL Explorer
query (
  $hirerId: String!
  $draftAdvertisement: SeekAnzAdProductAdvertisementDraftInput!
) {
  seekAnzHirerAdvertisementCreationProducts(
    hirerId: $hirerId
    draftAdvertisement: $draftAdvertisement
  ) {
    advertisementTypeCode
    name
    description
    price {
      amountExcludingTax {
        currency
        value
      }
      summary
      visibleForHirerIndicator
      taxedIndicator
    }
    enabledIndicator
    checkoutEstimate {
      paymentDueExcludingTax {
        currency
        value
      }
      summary
      contractConsumption {
        summary
        typeCode
      }
    }
    messages {
      severityCode
      visibilityCode
      content
    }
  }
}

Modifying existing job ad with SEEK contract

This is the default scenario for querying ad products for an existing job ad in the Playground environment.This pricing scenario assumes the hirer previously posted the job ad with the Classic ad product, and is intending to upgrade to the StandOut ad product behind a SEEK ad budget contract.
SEEK Contract - Edit
See field mapping for details on how the GraphQL response must be mapped to your panel.
QueryVariablesResult
CopyGraphQL Explorer
query (
  $advertisementId: String!
  $hirerId: String!
  $draftAdvertisement: SeekAnzAdProductAdvertisementDraftInput!
) {
  seekAnzHirerAdvertisementModificationProducts(
    hirerId: $hirerId
    advertisementId: $advertisementId
    draftAdvertisement: $draftAdvertisement
  ) {
    advertisementTypeCode
    name
    description
    price {
      amountExcludingTax {
        currency
        value
      }
      summary
      visibleForHirerIndicator
      taxedIndicator
    }
    enabledIndicator
    checkoutEstimate {
      paymentDueExcludingTax {
        currency
        value
      }
      summary
      contractConsumption {
        summary
        typeCode
      }
    }
    messages {
      severityCode
      visibilityCode
      content
    }
  }
}

New job ad with no SEEK contract

This scenario can be triggered by specifying draftAdvertisement.positionTitle in your input as [NO CONTRACT] while querying ad products for a new job ad in the Playground environment.This pricing scenario assumes the hirer has no SEEK contract, and has selected the Classic ad product.
No Contract - Create
See field mapping for details on how the GraphQL response must be mapped to your panel.
QueryVariablesResult
CopyGraphQL Explorer
query (
  $hirerId: String!
  $draftAdvertisement: SeekAnzAdProductAdvertisementDraftInput!
) {
  seekAnzHirerAdvertisementCreationProducts(
    hirerId: $hirerId
    draftAdvertisement: $draftAdvertisement
  ) {
    advertisementTypeCode
    name
    description
    price {
      amountExcludingTax {
        currency
        value
      }
      summary
      visibleForHirerIndicator
      taxedIndicator
    }
    enabledIndicator
    checkoutEstimate {
      paymentDueExcludingTax {
        currency
        value
      }
      summary
      contractConsumption {
        summary
        typeCode
      }
    }
    messages {
      severityCode
      visibilityCode
      content
    }
  }
}

Modifying existing job ad with no SEEK contract

This scenario can be triggered by specifying draftAdvertisement.positionTitle in your input as [NO CONTRACT] while querying ad products for an existing job ad in the Playground environment.This pricing scenario assumes the hirer previously posted the job ad with the Classic ad product, and is intending to upgrade to the StandOut ad product with no SEEK contract.
No Contract - Edit
See field mapping for details on how the GraphQL response must be mapped to your panel.
QueryVariablesResult
CopyGraphQL Explorer
query (
  $advertisementId: String!
  $hirerId: String!
  $draftAdvertisement: SeekAnzAdProductAdvertisementDraftInput!
) {
  seekAnzHirerAdvertisementModificationProducts(
    hirerId: $hirerId
    advertisementId: $advertisementId
    draftAdvertisement: $draftAdvertisement
  ) {
    advertisementTypeCode
    name
    description
    price {
      amountExcludingTax {
        currency
        value
      }
      summary
      visibleForHirerIndicator
      taxedIndicator
    }
    enabledIndicator
    checkoutEstimate {
      paymentDueExcludingTax {
        currency
        value
      }
      summary
      contractConsumption {
        summary
        typeCode
      }
    }
    messages {
      severityCode
      visibilityCode
      content
    }
  }
}

Field mapping

Below is a mapping of the Ad Selection Panel elements to the GraphQL response for the above pricing scenarios. For detailed information on all available fields, refer to the SeekAnzAdProduct schema definition.

1. Selected product and checkout estimate

A different border should be displayed for the selected ad product.The checkoutEstimate.summary field text should be displayed in place of the product description (see number 3) if there are no messages (see number 4).See New job ad with SEEK contract for an example of when to display checkoutEstimate.summary.

2. Contract usage

When the hirer has a contract with SEEK and it’s applicable to the product, show a contract bar above the product. You can determine if the hirer has a contract with SEEK based on data available within the checkoutEstimate.contractConsumption field.Display text in the bar from the checkoutEstimate.contractConsumption.summary field.Set the colour of the contract bar based on the checkoutEstimate.contractConsumption.typeCode field.There are three possible type codes for contract consumption: SameAdType, OtherAdType, and SameAdTypePlusInvoice. Each code must have a different colour.
  1. SameAdType indicates the contract can be used to purchase the product non-flexibly. For example, using a “Classic Pack” to purchase a Classic job ad.
  2. OtherAdType indicates the contract can be used to purchase the product flexibly. For example, using a “Classic Pack” to purchase a StandOut job ad.
  3. SameAdTypePlusInvoice indicates the contract pays for only a portion of the product price; the rest will be invoiced.
See New job ad with SEEK contract for an example of how to display contract usage.

3. Product description

Show the description field text. This is the description of the ad product.Hide this description if there are any items within messages to display (see number 4) or if the checkoutEstimate.summary field has any value (see number 1).

4. Messages

If there are items in the messages field for an ad product, they should take precedence in being displayed over the description in number 3 and checkoutEstimate.summary in number 1.The message content field text should be displayed, based on the following order of preference:
  1. When the ad product has been selected by the hirer, display the first item in the messages field with a visibilityCode of ProductSelected if present.
  2. Otherwise, display the first item in the messages field with a visibilityCode of Always.
If the message has a severityCode of Critical, the colour of the message should be different than if it is Informational:
  • Informational indicates a message with helpful information for a hirer.
  • Critical indicates a message with critical information for a hirer.
See Modifying existing job ad with no SEEK contract for an example of a Critical message outlining a price increase, as well as an Informational message outlining that an upgrade to Premium is unsupported.

5. Name

Display the name of the ad product from the name field text.

6. Price

Display the price from price.summary field text.Price should only be displayed to the hirer if the price.visibleForHirerIndicator field is true.The currency for the price is determined based on the hirer’s circumstances:
  • If the hirer has a contract, the currency will be based on the the contract’s location.For example, a New Zealand-based hirer will have prices displayed in the AUD currency if their contract was purchased within Australia.
  • If the hirer has no contract, the currency will be based on the hirer’s location.

7. Enabled indicator

The enabledIndicator field determines whether an ad type is selectable by the hirer while posting or updating their job ad.When the field is false:
  • The product must not be selectable.
  • The radio button should not be visible.
  • The product background should be greyed out.
  • Any messages should be displayed (see number 4).

8. Scheduling pricing caveat

You should include this message in your panel:
*Ad prices shown represent today’s prices only. If you schedule your job ad for a future date, you acknowledge and agree you’ll be charged the price of that ad at the date it’s published on SEEK’s website.
”

9. How are prices set

An info icon should appear at the end of the scheduling pricing caveat to help the hirer understand how SEEK sets ad prices. When the hirer hovers over or clicks on the info icon a tooltip should pop up and this message should be shown inside the tooltip:
Ad prices vary based on many factors including the supply of, and demand for, candidates for the advertised role. If your software allows scheduling, the price of an ad for a future date may change from the amount shown today.Learn about SEEK ad types 
”

10. About Premium ads

An info icon should appear at the end of the premium product type to help the hirer understand how Premium ads work. When the hirer hovers over or clicks on the info icon a tooltip should pop up and this message should be shown inside the tooltip:
About Premium adsPerfect for your most important or harder to source roles, when you want to target the right candidate faster. Using our extensive data, Premium ads maximise the way your role is promoted across desktop, email and mobile, giving it the best chance of being seen by the right candidate. Learn more > Premium ad prices reflect the competition for candidates in a role and location. When competition for candidates is high, prices will be higher. When competition is lower, prices will be lower.
”

Posting the job ad

When a hirer selects an ad product, the advertisementTypeCode field returned by the ad product query should be persisted in memory.When the hirer is ready to post or update the job ad, advertisementTypeCode should then be passed into the CreatePostingInstructionInput.seekAnzAdvertisementType field in the postPosition, postPositionProfileForOpening or updatePostedPositionProfile job posting mutations.

Forward compatibility

The set of available ad products and the number of ad products presented to a hirer may change in the future. Your software should not have conditional business logic based on individual ad products.Products should be presented to hirers in the same order they are returned in the response.Your software should conditionally display bullet points and branding inputs based on the selected ad product. Instead of basing this on advertisementTypeCode, it should use the features.searchBulletPointsIndicator and features.brandingIndicator fields.
Ad selection (V1): Panel
Archived: Questionnaires (V1)