Docs Archived 2022 SEEK API migration Job Posting API 2. Object identifiers

Phase 2: Object identifiers

This content has been archived. It may contain guidance that is no longer relevant.

The retired Job Posting API used a few different types of identifiers:

Hirers & agents were identified using numeric SEEK advertiser IDs. These were provided by SEEK’s support team when onboarding a new SEEK hirer.
Short, human-readable strings were used to specify locations & job categories. These were distributed in an “expected values” spreadsheet.
UUIDs were used to identify job ads after they’ve been posted. The job ad’s UUID was returned in the HTTP response when initially creating the job ad.

By contrast, the SEEK API uses opaque object identifiers to uniquely identify each object in the SEEK API. For example, this is an identifier for a job category in the Playground environment: seekAnzPublicTest:jobCategory:seek:2PiXemmouInstead of distributing a spreadsheet of expected values, the SEEK API provides GraphQL queries to find input object identifiers. This enables new hirer experiences such as interactively suggesting locations & job categories.To support your migration, the Job Posting API was updated to support object identifiers. This allowed you to integrate with the new SEEK API objects listed below before migrating from the Job Posting API for managing jobs.

Hirer IDs

The SEEK API uses opaque object identifier strings to identify SEEK hirers. To ease migration to the SEEK API, the Job Posting API accepted hirer object identifiers in the existing thirdParties.advertiserId field.

Hirer ID

Copy

  "thirdParties": {

    "advertiserId": "seekAnzPublicTest:organization:seek:93WyyF1h"

For more information, see the hirer identifier guide.

Job ad input objects

Hirers select from a number of associated objects when posting a SEEK job ad:

The retired Job Posting API did not support programmatic retrieval of these objects. For some objects, SEEK distributed a spreadsheet of “expected values” to be hardcoded in your software. For others, the hirer would manually enter an identifier as part of your posting flow.The SEEK API supports queries to list or suggest these objects in real time. This allows your hirers to use the most up-to-date SEEK datasets when they post their jobs.

Locations

SEEK uses proprietary IDs to specify the location of positions. Precisely locating positions helps candidates search for the most relevant jobs. They are also used as an input into SEEK’s ad pricing.The Job Posting API used a location.id field refined with an optional location.areaId. For example, the Melbourne location included the MelbourneCBDInnerSuburbs area. SEEK’s ANZ location taxonomy had to be manually hardcoded into your software.The SEEK API uses a multi-level hierarchy from larger parent locations to smaller child locations. Each node in the hierarchy is uniquely identified by a single object identifier. Instead of hardcoding the location hierarchy, you’re encouraged to dynamically retrieve locations via GraphQL queries:

locationSuggestions returns an array of likely locations for a provided text string.
nearestLocations returns an array of locations closest to the specified latitude & longitude, ordered by distance.

To ease migration to the SEEK API, the Job Posting API accepts location object identifiers in the existing location.id field. The optional location.areaId field should be omitted when using object identifiers.

Location OID

Copy

  "location": {

    "id": "seekAnzPublicTest:location:seek:2m81wybwV"

For more information on locations in the SEEK API, see the locations documentation.

Job categories

Job categories identify the occupational category of a position. Accurately categorising positions helps candidates search for the most relevant jobs. They are also used as an input into SEEK’s ad pricing.The Job Posting API used human-readable IDs such as DevelopersProgrammers. SEEK’s ANZ job category taxonomy had to be manually hardcoded into your software.The SEEK API uses object identifiers and supports programmatic retrieval via GraphQL queries:

jobCategories returns an array of top-level job categories for a given scheme.
jobCategorySuggestions returns an array of suggested job categories based on a partial PositionProfile.

To ease migration to the SEEK API, the Job Posting API accepts job category object identifiers in the existing subclassificationId field.

Job category OID

Copy

  "subclassificationId": "seekAnzPublicTest:jobCategory:seek:2EFstqFvP"

For more information on job categories in the SEEK API, see the job categories documentation.

Branding

Branding allows hirers to promote their company brand on their job ads and apply forms. They are manually managed by hirers in the Logos & Brands section of the SEEK Employer website.The Job Posting API had no mechanism to retrieve hirer brands; hirers had to manually enter a logo ID in your posting flow.The SEEK API supports returning a paginated list of a hirer’s brands using the advertisementBrandings query.If your software currently supports logos, it passes a numeric logo ID to the Job Posting API:

Numeric logo ID

Copy

  "standout": { "logoId": 12345 }

To ease migration to the SEEK API, a new string field named brandingId was added to the Job Posting API that accepts a brand OID or a stringified logo ID:

Brand OIDStringified logo ID

Copy

  "standout": {

    "brandingId": "globalPublicTest:advertisementBranding:hirerBranding:37EWfWxhwVEGTT5BcjfE2L"

You must not use logoId and brandingId at the same time. You should replace your current usage of logoId with brandingId and convert the numeric logo IDs to strings.

For more information on these queries, see the branding documentation.

Questionnaires

A hirer can optionally include a questionnaire for candidates to answer in SEEK’s Apply Form. Their responses are made available through the Optimised Apply use case. Questionnaires are rendered on SEEK’s candidate website and in our mobile apps.Some Job Posting API integrations made use of SEEK Screen, a legacy feature that allowed hirers to manage questionnaires on the SEEK Employer website and manually enter a numeric ID in your posting flow.The SEEK API does not support SEEK Screen for new integrations. You can either replace the feature with SEEK API questionnaires, or remove it entirely if it sees low usage in your software.To ease migration to the SEEK API, a new string field named questionnaireId has been added to the Job Posting API that accepts an application questionnaire OID:

Questionnaire OID

Copy

  "questionnaireId": "seekAnzPublicTest:applicationQuestionnaire:rrv2:SqFmkV8S2dMipyqbHjD9Mr"

Exit criteria

In order to move to the next phase, you will need to have completed the following:

Criteria	Description
Locations supported	Hirer can select from a list of locations
Job categories supported	Hirer can select from a list of job categories
Branding supported	Hirer can select from a list of brands
Questionnaires supported	Hirer can create a new questionnaire (if applicable)
Job ad posted successfully	Hirer can successfully post a job ad with objects retrieved or created via the SEEK API
Job ad updated successfully	Hirer can successfully update a job ad with objects retrieved or created via the SEEK API

Job Posting API: 1. Auth

Job Posting API: 3. Ad selection