Hirer relationships

Hirer relationships

The SEEK API authorises 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.
SEEK’s support team must explicitly configure these relationships as part of onboarding a SEEK hirer to your software. GraphQL operations will fail with a FORBIDDEN error if a required relationship hasn’t been configured.
You can view a list of your SEEK hirers and their relationships on the Developer Dashboard’s hirers page .

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
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
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
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": "eb1386f2-2364-4cf5-b85f-23b8de1c2b80",
      "createDateTime": "2021-08-04T01:03:35.610Z",

      "type": "HirerRelationshipChanged",

      "hirerId": "seekAnzPublicTest:organization:seek:93WyyF1h"
    }
  ],
  "subscriptionId": "seekAnzPublicTest:webhookSubscription:events:RNzsabxEX56cuRepCD9A8j"
}
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.