Docs  Job Posting  Ad Sync  Share positions
  • No results found

Share positions

When positions are created and updated in your software, propagate those changes to SEEK.

Field mapping

Ad Sync uses a similar data structure to the postPosition mutation.A brief summary of important fields is provided below.
Field
Path
Example
Requirement
Identifier
seekPartnerPositionId
seekPartnerPositionId
Mandatory
Hiring organization
postingRequester
postingRequester
Mandatory
Title
positionTitle
Senior Business Analyst
Mandatory
Location
positionLocation
positionLocation
Mandatory
Description
positionFormattedDescriptions
positionFormattedDescriptions
Mandatory
Work type
seekAnzWorkTypeCode
FullTime
Mandatory
Work arrangements
seekWorkArrangementCodes
OnSite
Mandatory
Salary
offeredRemunerationPackage
offeredRemunerationPackage
Mandatory
Application URL
postingInstructions.applicationMethods
https://example.com/position/123/apply
Mandatory to link out
Search bullet points
positionFormattedDescriptions
positionFormattedDescriptions
Recommended
Search summary
positionFormattedDescriptions
positionFormattedDescriptions
Recommended
Listing date
postingInstructions.start
2048-01-01T00:00:00.000Z
Recommended
Closing date
postingInstructions.end
2048-01-31T00:00:00.000Z
Recommended

seekPartnerPositionId

To reduce job ad duplication, provide a stable identifier that your software uses to uniquely identify the position.
Request snippet
Copy
"REQ-123"
Ensure that your software provides the same seekPartnerPositionId across all operations relating to the position.

postingRequester

When sharing a position, include the corresponding SEEK hirer id, as well as a stable identifier that your software uses to uniquely identify the hiring organization, seekPartnerHirerId.
Existing SEEK hirer
Copy
{
  "id": "seekAnzPublicTest:organization:seek:93WyyF1h",
  "seekPartnerHirerId": "abc-123"
}
Directional Ad Sync will be extended in a later release to allow your software to share positions from a hirer that is yet to onboard to SEEK. A new SEEK hirer ID will be provisioned and returned in the response; store this ID and use it when sharing subsequent positions for the same hirer.
Request snippetResponse snippet
Copy
{
  "communication": {
    "address": {
      "line": "Wallaman Falls, Lookout Rd",
      "city": "Wallaman",
      "countrySubDivisions": {
        "type": "State",
        "value": "QLD"
      },
      "postalCode": "4850",
      "country": "AU"
    },
    "phone": {
      "formattedNumber": "1900 654 321"
    }
  },
  "name": "Acme Corp",
  "personContacts": {
    "name": { "formattedName": "Francis Admin" },
    "roleCode": "AccountAdministrator",
    "communication": {
      "email": [{ "address": "francis.admin@example.com" }],
      "phone": [{ "formattedNumber": "1800 160 401" }]
    }
  },
  "seekPartnerHirerId": "abc-123"
}

positionLocation

Provide city or suburb granularity for each position. Precisely locating positions helps candidates search for the most relevant jobs.
Structured dataGeolocation
Copy
{
  "city": "Wallaman",
  "countrySubDivisions": {
    "type": "State",
    "value": "QLD"
  },
  "postalCode": "4850",
  "country": "AU"
}
If a hirer is recruiting for a remote position that is not tied to a specific geographical location, set seekWorkArrangementCodes to Remote. A location is still required for a remote position; this can be set to the headquarters or local branch of the hirer’s organization.

positionFormattedDescriptions

Descriptions for the position are supplied in an array.Provide a complete representation of the position in AdvertisementDetails, including paragraphs and formatting to make the content easier to read. Do not truncate with … or similar.
Request snippet
Copy
[
  // Short description to be shown in search results
  {
    "descriptionId": "SearchSummary",
    "content": "Seasoned BA sought to lead strategic initiatives."
  },


  // Three bullet points to display in search results
  {
    "descriptionId": "SearchBulletPoint",
    "content": "Stakeholder management and facilitation"
  },
  {
    "descriptionId": "SearchBulletPoint",
    "content": "Process mapping and requirement elicitation"
  },
  {
    "descriptionId": "SearchBulletPoint",
    "content": "Data-driven decision making"
  },


  // Detailed description to appear on a job ad
  {
    "descriptionId": "AdvertisementDetails",
    "content": "<p>Acme Inc is seeking a business analyst to partner with business and technology teams to deliver high-impact, data-informed change.</p><p>You will lead discovery, define clear and testable requirements, map current and future processes, and support delivery through to adoption.</p><p>Bring strong stakeholder engagement, facilitation skills, and a pragmatic approach to complex problem solving.</p>"
  }
]

offeredRemunerationPackage

Provide the pay type, salary range, and description of the remuneration package.
Request snippet
Copy
{
  "basisCode": "Salaried",


  // 100,000–130,000 Australian dollars per year
  "ranges": {
    "minimumAmount": {
      "value": 100000,
      "currency": "AUD"
    },
    "maximumAmount": {
      "value": 130000,
      "currency": "AUD"
    },
    "intervalCode": "Year"
  },


  // Remuneration description visible to the candidate
  "descriptions": ["Competitive salary, plus super"]
}
  • The pay type is expressed using a combination of two fields:
    1. The basisCode defines how the remuneration for the position is calculated
    2. The intervalCode defines the period of time the minimum & maximum amounts are calculated over
  • The salary range is specified in the major currency unit (e.g. dollars)The range is used to provide more relevant job search results to candidates, but the monetary values in minimumAmount and maximumAmount are not visible in search results nor on the job ad.
  • The remuneration description is displayed to candidatesThe description should be a short summary of the package, including further benefits such as bonus options and superannuation. Note that this field has a maximum length of 50 characters, which roughly corresponds to a single English sentence.SEEK may display the supplied currency and intervalCode alongside the description for clarity.

Implementation options

Option 1: Full state sync

Use the GraphQL syncPositions mutation to share position data with SEEK.
MutationVariablesResult
CopyGraphQL Explorer
{
  "input": {
    "positionOpening": {
      "postingRequester": {
        // Hirer we're sharing the position on behalf of
        "id": "seekAnzPublicTest:organization:seek:93WyyF1h",
        "seekPartnerHirerId": "abc-123",


        // Contact people for the position
        "personContacts": [
          {
            "name": { "formattedName": "Jeff Manager" },
            "roleCode": "HiringManager",
            "communication": {
              "email": [{ "address": "jeff.manager@example.com" }],
              "phone": [{ "formattedNumber": "03 8517 4100" }]
            }
          }
        ]
      },


      // Unique identifier of the position in your software
      "seekPartnerPositionId": "position-requisition-123",


      // Express intent to automatically advertise the position based on status
      "seekPositionIntent": "AdSync",


      // The status of the position in your software
      // This can be set to "Active" once it is ready to be advertised externally
      "statusCode": "Incomplete"
    },
    "basePositionProfile": {
      "positionTitle": "Señor business analyst",


      "positionFormattedDescriptions": [
        // Short description to be shown in search results
        {
          "descriptionId": "SearchSummary",
          "content": "Seasoned BA sought to lead strategic initiatives."
        },


        // Three bullet points to display in search results
        {
          "descriptionId": "SearchBulletPoint",
          "content": "Stakeholder management and facilitation"
        },
        {
          "descriptionId": "SearchBulletPoint",
          "content": "Process mapping and requirement elicitation"
        },
        {
          "descriptionId": "SearchBulletPoint",
          "content": "Data-driven decision making"
        },


        // Detailed description to appear on a job ad
        {
          "descriptionId": "AdvertisementDetails",
          "content": "<p>Acme Inc is seeking a business analyst to partner with business and technology teams to deliver high-impact, data-informed change.</p><p>You will lead discovery, define clear and testable requirements, map current and future processes, and support delivery through to adoption.</p><p>Bring strong stakeholder engagement, facilitation skills, and a pragmatic approach to complex problem solving.</p>"
        }
      ],


      // 100,000–130,000 Australian dollars per year
      "offeredRemunerationPackage": {
        "basisCode": "Salaried",
        "ranges": {
          "minimumAmount": {
            "value": 100000,
            "currency": "AUD"
          },
          "maximumAmount": {
            "value": 130000,
            "currency": "AUD"
          },
          "intervalCode": "Year"
        },


        // Remuneration description visible to the candidate
        "descriptions": ["Competitive salary, plus super"]
      },


      "seekAnzWorkTypeCode": "FullTime",
      "seekWorkArrangementCodes": "OnSite",


      // YouTube video to embed above the job ad's details
      "seekVideo": {
        "url": "https://www.youtube.com/watch?v=Q3UvigPHCjI"
      },


      "positionLocation": {
        "geoLocation": {
          "latitude": -18.592222,
          "longitude": 145.801389
        }
      },


      "postingInstructions": {
        "applicationMethods": [
          {
            "applicationUri": {
              "url": "https://example.com/position/123/apply"
            }
          }
        ]
      }
    },
    "updateDateTime": "2048-01-01T00:00:00.000Z"
  }
}
When the position is updated in your software, forward its full state to the same syncPositions mutation, which functions as a PUT operation.Setting positionOpening.statusCode to Active will trigger the Ad Sync engine to evaluate the position. This status is appropriate when the position is ready to be advertised externally, which may depend on:
  • The status of the job requisition in your software
  • Fields that are only collected in the job posting flow in your software, such as a detailed advertisement description and branding assets
When the position closes, forward its full state—including positionOpening.statusCode as Closed—to the same syncPositions mutation. The closure will propagate to job ads under the requisition.

Option 2: Granular updates

Directional Contact us if technical constraints prevent your software from synchronising the full position state whenever it changes. Ad Sync may provide an alternative option of creating the position with syncPositions, then performing granular update operations against the underlying PositionOpening and PositionProfile objects.

Status

Setting positionOpening.statusCode to Active will trigger the Ad Sync engine to evaluate the position. This status is appropriate when the position is ready to be advertised externally, which may depend on:
  • The status of the job requisition in your software
  • Fields that are only collected in the job posting flow in your software, such as a detailed advertisement description and branding assets
MutationVariablesResult
CopyGraphQL Explorer
{
  "input": {
    "positionOpening": {
      "documentId": "globalPublicTest:positionOpening:positions:E3Lz6HkSrbZCawh4gPGAtM",
      "statusCode": "Active"
    }
  }
}
When the position closes, shift its status to Closed. The closure will propagate to job ads under the requisition.
MutationVariablesResult
CopyGraphQL Explorer
{
  "input": {
    "positionOpening": {
      "documentId": "globalPublicTest:positionOpening:positions:E3Lz6HkSrbZCawh4gPGAtM",
      "statusCode": "Closed"
    }
  }
}

Contacts

MutationVariablesResult
CopyGraphQL Explorer
mutation ($input: UpdatePositionOpeningPersonContactsInput!) {
  updatePositionOpeningPersonContacts(input: $input) {
    positionOpening {
      documentId {
        value
      }
    }
  }
}

Details

MutationVariablesResult
CopyGraphQL Explorer
mutation ($input: UpdateUnpostedPositionProfileInput!) {
  updateUnpostedPositionProfile(input: $input) {
    positionProfile {
      profileId {
        value
      }
    }
  }
}

Sharing considerations

When implementing Ad Sync in your software, you will need to make two related design decisions:
  1. Whether to share positions in near real time or on a periodic interval
  2. Whether to share positions individually or in batches

Real time vs periodic interval

We recommend implementing an event-based system in your software to trigger Ad Sync from position changes in near real time.If your software has constraints that prevent such a design, share positions in batches periodically, with a maximum interval of 1 hour. Include an updateDateTime that represents when the last update to the position actually occurred in your software; it must not represent when the batch of positions is later sent to SEEK.
Event
Timestamp
Use as updateDateTime?
Hirer saves change to position description
2048-01-01T09:45:32.617Z
Partner synchronises position updates for the past 1 hour
2048-01-01T10:00:00.000Z
Your software is forbidden from indiscriminately re-synchronising all positions at each interval; Ad Sync must only be triggered for positions that actually changed within the period.

Individual vs batched

While most of our code samples provide a single position to the syncPositions mutation for simplicity, multiple positions can be shared at once.This is useful if your software may share more than one position at a time, including if it:
  • Synchronises positions on a periodic interval rather than in near real time
  • May modify multiple positions at once (e.g. due to process automation)
  • Supports resending historical data (e.g. to correct data quality issues)
Up to 25 positions can be included in one syncPositions operation. If you have more than 25 positions to send, split them into chunks of 25 and run multiple operations, monitoring the SEEK API responses for rate limiting errors.
Job Posting: Ad Sync
Ad Sync: Display job ads