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-productsscope 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:
seekAnzHirerAdvertisementCreationProductsretrieves ad products when initially posting a job ad.seekAnzHirerAdvertisementModificationProductsretrieves ad products when updating a job ad with a knownprofileId.seekAnzHirerAdvertisementModificationProductsAltretrieves 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
jobCategoriesquery make sure you only usechildrenjob 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.
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
}
}
}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.
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
}
}
}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.
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
}
}
}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.
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
}
}
}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.SameAdTypeindicates the contract can be used to purchase the product non-flexibly. For example, using a “Classic Pack” to purchase aClassicjob ad.OtherAdTypeindicates the contract can be used to purchase the product flexibly. For example, using a “Classic Pack” to purchase aStandOutjob ad.SameAdTypePlusInvoiceindicates 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
messagesfield with avisibilityCodeofProductSelectedif present. - Otherwise, display the first item in the
messagesfield with avisibilityCodeofAlways.
If the message has a
severityCode of Critical, the colour of the message should be different than if it is Informational:Informationalindicates a message with helpful information for a hirer.Criticalindicates 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.