Hirer relationships

The SEEK API authorizes operations based on a set of relationships between you and your SEEK hirers. Each use case requires a corresponding relationship to allow you to act on behalf of the hirer:Functionality shared between use cases will accept multiple relationship types. For example, position openings can be managed with either a JobPosting or ProactiveSourcing relationship.You can view a list of your SEEK hirers and their relationships on the Developer Dashboard’s hirers page.

Hirer onboarding

SEEK must explicitly configure hirer relationships as part of onboarding a SEEK hirer to your software. Direct hirers to the SEEK ‘Link your Software’ page for the appropriate market:GraphQL operations will fail with a FORBIDDEN error if a required relationship hasn’t been configured. You should contact the hirer in cases where this is unexpected.SEEK hirers in specific market segments commonly have multiple SEEK accounts aligned to divisions within their organizations. It’s important that your platform supports hirers with multiple SEEK accounts per Section B, Clause 73b of the SEEK API Terms of Use .SEEK will provide the hirer with their hirer ID for configuration in your software. At the same time, the SEEK API will emit a HirerRelationshipChanged event. While you can source the hirer ID from this event, manual triage is still necessary to link the SEEK hirer with the relevant account in your software.If you capture the hirer ID in a self-service text field:
  1. The field must accept the hirer ID in full.Per the earlier SEEK API conventions section, object identifiers must not be disassembled into their component parts.
  2. The value must be trimmed before it is passed to the SEEK API.The SEEK API will not recognise hirer IDs with leading or trailing whitespace.
  3. The value may be validated upfront through the SEEK API.You can make a hiringOrganization query to provide faster feedback to hirers when they enter an invalid ID.
  4. The association must be appropriately triaged and authorized by your team.A hirer must not be able to enter another hirer’s ID into your software and gain access to their data.
Hirer ID with hardcoded prefix (1)
seekAnzPublicTest:organization:seek:␣93WyyF1h
Hirer ID without trimming (2)
seekAnzPublicTest:organization:seek93WyyF1h␣
Hirer ID with trimming
seekAnzPublicTest:organization:seek93WyyF1h

Before you begin

Before you start querying hirer relationships, you will need to request a partner token.These queries also work with a browser token but will only return the hirer the browser token is scoped to. For the browser token to work, you will need to include the query:organizations scope in your request.

Operations

hiringOrganization

The hiringOrganization query will list your configured relationships with a SEEK hirer. If no relationship has been configured the query will fail with a FORBIDDEN error.The “Look up a hirer by ID” section of the Developer Dashboard’s hirers page wraps this query in a friendly user interface.
QueryVariablesResult
CopyGraphQL Explorer
query ($id: String!) {
  hiringOrganization(id: $id) {
    name
    seekApiCapabilities {
      relationshipTypeCodes
    }
  }
}

hiringOrganizations

The hiringOrganizations query will return a paginated list of all SEEK hirers you have a given relationship with.The “Search all hirers” section of the Developer Dashboard’s hirers page wraps this query in a friendly user interface.
QueryVariablesResult
CopyGraphQL Explorer
query ($schemeId: String!, $relationshipTypeCodes: [String!]!, $first: Int) {
  hiringOrganizations(
    schemeId: $schemeId
    filter: { relationshipTypeCodes: $relationshipTypeCodes }
    first: $first
  ) {
    edges {
      node {
        id {
          value
        }
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

self

When using a browser token, the self query will return the hirer the browser token is scoped to. This can be used to list a hirer’s relationships directly from your frontend without having to explicitly specify the hirer’s ID.
QueryResult
CopyGraphQL Explorer
query {
  self {
    hirer {
      id {
        value
      }
      name
      seekApiCapabilities {
        relationshipTypeCodes
      }
    }
  }
}

Events

HirerRelationshipChanged events are emitted whenever a relationship between you and a hirer is added or removed. The hirer relationships in your software can be kept in sync with SEEK using these events.This is an example of a webhook body containing a HirerRelationshipChanged event:
JSON
Copy
{
  "events": [
    {
      "id": "seekAnzPublicTest:event:events:RJrWs6Kw13TvACTTXG6qZg",
      "type": "HirerRelationshipChanged",


      "createDateTime": "2020-10-20T23:13:58.804Z",


      "hirerId": "seekAnzPublicTest:organization:seek:93WyyF1h"
    }
  ],
  "subscriptionId": "seekAnzPublicTest:webhookSubscription:events:RNzsabxEX56cuRepCD9A8j",
  "url": "https://example.com/webhook"
}
Once you receive an event, you can use its hirerId to query the current state of your relationship with that hirer from the hiringOrganization query.If all relationships have been removed with the hirer, a FORBIDDEN error will be returned.
Auth: Browser tokens
Getting started: GraphQL