Hirer relationships

    Suggestions will appear below the field as you type

    Hirer relationships

      Suggestions will appear below the field as you type

      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.
      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 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 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 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