Position openings

Position openings

A PositionOpening represents an open position at a hirer’s organization. For example, a position opening might be created once a hirer approves a job requisition for a new role.
A newly created PositionOpening consists of an owner and a status code. The details of the position itself (e.g. its title & location) are contained in PositionProfiles created within the opening:
  • A PostedPositionProfile represents a job ad posted to the SEEK job board.
    Hirers might continue to post job ads within the same opening while the position remains unfilled. They could also use multiple job ads to cover different locations and job categories.
    Grouping multiple job ads within a single opening is provided for your convenience. There is no business impact from grouping (or not grouping) job ads together.
  • Your software would share these with SEEK to support Proactive Sourcing. Grouping unposted positions with their related job ads helps SEEK match potential candidates against the opening.
While all job ads need to belong to a position opening, your software can create a new position opening for each job ad. The postPosition mutation is provided to create a new position opening and post a job ad in a single operation.
The SEEK employer website and deprecated Job Posting API do not have an analogous concept of an open position. Job ads posted through those channels will have a synthetic PositionOpening created for each of their PositionProfiles. Synthetic position openings cannot be paginated, updated or deleted.

Before you begin

Before you start with position opening queries, you will need to request a partner token.

Operations

createPositionOpening

The createPositionOpening mutation creates an empty PositionOpening . The postingRequester indicates the SEEK hirer and the contact information of the opening’s owner.
MutationVariablesResult
mutation ($input: CreatePositionOpeningInput!) {
  createPositionOpening(input: $input) {
    positionOpening {
      documentId {
        value
      }
    }
  }
}
A name and email address of at least one person must be provided in personContacts; SEEK may contact them if there is a problem with their job ad. Note that physical addresses and phone numbers may be omitted:
JSON
Copy
// `positionOpening.postingRequester.personContacts[].communication`
{
  "email": [{ "address": "jeff.manager@example.com" }],
  // This can be set to an empty array.
  "phone": [],
  // This can be omitted or set to an empty array.
  "address": []
}

updatePositionOpeningStatus

A position opening’s status is intended to help hirers manage their position openings; it isn’t used directly by the SEEK API. For example, you can filter on a particular status when paginating position openings.
MutationVariablesResult
mutation ($input: UpdatePositionOpeningStatusInput!) {
  updatePositionOpeningStatus(input: $input) {
    positionOpening {
      statusCode
    }
  }
}
After an opening has been created you can use separate mutations to create nested PositionProfiles . For example, the postPositionProfileForOpening mutation will create a job ad within the opening.

updatePositionOpeningPersonContacts

The updatePositionOpeningPersonContacts mutation updates the postingRequester contact details of the PositionOpening .
MutationVariablesResult
mutation ($input: UpdatePositionOpeningPersonContactsInput!) {
  updatePositionOpeningPersonContacts(input: $input) {
    positionOpening {
      documentId {
        value
      }
    }
  }
}

positionOpening

The positionOpening query returns information about an existing position opening. You can select fields from its nested PositionProfiles to help identify the position.
QueryVariablesResult
query ($id: String!) {
  positionOpening(id: $id) {
    documentId {
      value
    }
    statusCode
    positionProfiles {
      profileId {
        value
      }
      positionTitle
    }
    postingRequester {
      id {
        value
      }
    }
    seekPartnerMetadata
  }
}

positionOpenings

The positionOpenings query returns a paginated list of position openings for a given hirer. Only position openings created by the SEEK API will appear in the paginated list.
You can optionally use a statusCode filter to only return position openings with the desired status.
QueryVariables
query ($hirerId: String!, $statusCode: String) {
  positionOpenings(hirerId: $hirerId, filter: { statusCode: $statusCode }) {
    edges {
      node {
        positionProfiles {
          profileId {
            value
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

deletePositionOpening

Because every position profile must be nested inside an opening, you must delete all nested position profiles first:
  • Unposted position profiles can be deleted using the deleteUnpostedPositionProfile mutation .
  • The position profiles of job ads cannot be explicitly deleted; they will be automatically deleted 180 days after the job ad closes.
To soft delete a position opening you can instead update its status to Closed. You can then filter on Active position openings when using the positionOpenings query .
MutationVariablesResult
mutation ($input: DeletePositionOpeningInput!) {
  deletePositionOpening(input: $input) {
    positionOpening {
      documentId {
        value
      }
    }
  }
}