This content has been archived. You may be looking for its latest revision.
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.
- 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.
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.
The SEEK API provides three queries for retrieving ad products:
seekAnzHirerAdvertisementCreationProducts
retrieves ad products when initially posting a job ad.seekAnzHirerAdvertisementModificationProducts
retrieves ad products when updating a job ad with a knownprofileId
.seekAnzHirerAdvertisementModificationProductsAlt
retrieves ad products when updating a job ad without a knownprofileId
.Your software must provide the state of the job ad before the hirer’s requested updates.
You should invoke the above queries whenever a hirer updates one of these fields:
- Ad products can only be priced using a child job category. When using the
jobCategories
query make sure you only usechildren
job categories, not the top-level categories returned by the query.
Note: These fields affect the price of the job ad.
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.
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.See field mapping for details on how the GraphQL response must be mapped to your panel.
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
}
}
}
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.See field mapping for details on how the GraphQL response must be mapped to your panel.
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
}
}
}
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.See field mapping for details on how the GraphQL response must be mapped to your panel.
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
}
}
}
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.See field mapping for details on how the GraphQL response must be mapped to your panel.
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
}
}
}
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 .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
.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.SameAdType
indicates the contract can be used to purchase the product non-flexibly. For example, using a “Classic Pack” to purchase aClassic
job ad.OtherAdType
indicates the contract can be used to purchase the product flexibly. For example, using a “Classic Pack” to purchase aStandOut
job ad.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.
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).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:- When the ad product has been selected by the hirer, display the first item in the
messages
field with avisibilityCode
ofProductSelected
if present. - Otherwise, display the first item in the
messages
field with avisibilityCode
ofAlways
.
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.Display the name of the ad product from the
name
field text.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.
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).
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.
”
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 system allows scheduling, the price of an ad for a future date may change from the amount shown today.
”
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 ads
Perfect 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.
”
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.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.