Ad selection with GraphQL

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 are invoked when you edit these fields on your system:
Note: These fields affect the price of the job ad.

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.
Please note: The prices presented in each of these scenarios are for demonstration purposes only.
New job ad with SEEK contract
This 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
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 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
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
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
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
    When the enabledIndicator 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).

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.