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:
- An
ApplicationExport
relationship allows you to export the hirer’s candidate profiles & attachments. - A
JobPosting
relationship allows you to price, post & update job ads on behalf of the hirer. - A
ProactiveSourcing
relationship allows you to upload candidates & unposted positions belonging to 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 .
SEEK’s support team must explicitly configure hirer 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.
The hirer should be contacted in cases where this is unexpected.SEEK will provide the hirer and/or your support team 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:
- 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.
- 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.
- 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. - The association must be appropriately triaged and authorised 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 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.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.
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.
query ($schemeId: String!, $relationshipTypeCodes: [String!]!, $first: Int) {
hiringOrganizations(
schemeId: $schemeId
filter: { relationshipTypeCodes: $relationshipTypeCodes }
first: $first
) {
edges {
node {
id {
value
}
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
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.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.