Interaction history

    Suggestions will appear below the field as you type

    Interaction history

      Suggestions will appear below the field as you type

      Interaction history

      Interaction history

      You can share candidate interactions that occur in your software.
      This provides hirers with a consolidated view of interactions across your software and SEEK:
      Changes to candidate interaction history within your software should be reflected in the SEEK API within 60 seconds.

      Data structure

      Individual interactions are represented by a CandidateProcessHistoryItem type . Each item is associated with the CandidateProfile  of an uploaded candidate and listed under the seekProcessHistory field.

      General interactions

      An interaction may occur outside of the context of a particular position:
      JSON
      Copy
      {
        "action": {
          "code": "Note",
          "name": "Contact again later",
          "description": "Candidate not currently looking for work, try again in six months. Keen to stay in Melbourne."
        },
        "actionDate": "1999-07-26T23:48:58.775Z",
        "idempotencyId": "00000000-0000-0000-0000-000000000001",
        "primaryParties": [
          {
            "person": {
              // For interaction history, `communication` fields are not displayed in
              // SEEK Talent Search
              // They can be omitted or set to empty arrays
              "communication": {
                "email": [],
                "phone": []
              },
              "name": {
                "formattedName": "Terry A",
                "given": "Terry",
                "family": "Astley"
              }
            }
          }
        ]
        // `positionProfile` and `seekSource` are omitted for a general interaction
        // `status` is omitted for a non-`CandidateWorkflowTransition` action
      }
      • action has a freeform name, description and one of the following codes:
        Code
        Definition
        AgencySubmission
        A candidate was sent by an agency to the hirer for general consideration
        Document
        A document was attached
        Email
        An email was sent
        Note
        A note was added
        PhoneCall
        A phone call was made
        PostPlacementActivity
        A post-placement activity occurred, e.g. a satisfaction survey
        Screening
        A screening activity occurred, e.g. an interview
        VerificationActivity
        A verification activity occurred, e.g. a police check
        StatusChange
        The availability of the candidate has changed
        Other
        Any other action that doesn’t fit into the other buckets
        name is the hirer-visible name for the workflow step. For example, the hirer might have defined a “Second interview” step that maps to the SEEK API’s Screening action code.

      Placement information

      An interaction may be scoped to a given opportunity by providing the associated position profile:
      JSON
      Copy
      {
        "action": {
          "code": "CandidateWorkflowTransition",
          "name": "Initial offer",
          "description": "Progressed to offer stage"
        },
        "actionDate": "1999-12-26T12:31:43.185Z",
        "idempotencyId": "00000000-0000-0000-0000-000000000002",
        "primaryParties": [
          {
            "person": {
              "communication": {
                "email": [],
                "phone": []
              },
              "name": {
                "formattedName": "Hayden R",
                "given": "Hayden",
                "family": "Robinson"
              }
            }
          }
        ],
        // `positionProfile` and `seekSource` are required for placement information
        "positionProfile": {
          "profileId": "globalPublicTest:positionProfile:unposted:QnwpqZfzXu1NRmZw5tjswn"
        },
        "seekSource": {
          "name": "Recruitment Agency"
        },
        // `status` is required for a `CandidateWorkflowTransition` action
        "status": {
          "code": "Offer"
        }
      }
      • action may use any of the prior codes, with one addition:
        Code
        Definition
        CandidateWorkflowTransition
        The status of the candidate for this opportunity has changed
      • seekSource indicates the initial source of the candidate in the context of this opportunity. The same value should be resent for each item in the process.
      • status must be provided for a CandidateWorkflowTransition action, following a rough order of progression:
        Code
        Definition
        Application
        Initial state in the hiring process
        AgencyShortlist
        Shortlisted internally by an agency prior to submission to the hirer
        AgencySubmission
        Sent by an agency to the hirer for consideration for this opportunity
        HirerShortlist
        Shortlisted by the hirer
        Interview
        Interviewing/interviewed for the opportunity
        TestingOrQualificationsCheck
        Completing/completed tests or verification of their qualifications
        ReferenceCheck
        Having/had their references checked
        Offer
        Offered the position
        Successful
        Accepted the position
        Unsuccessful
        No longer being considered for the position

      Operations

      Create a candidate process history item

      The createCandidateProcessHistoryItem mutation  adds a record of an interaction between the candidate and a SEEK hirer.
      To avoid unintentional duplication of data, SEEK enforces uniqueness on a partner-provided idempotencyId. A request to create an existing item will receive a CreateCandidateProcessHistoryItemPayload_Conflict result. The existing item will not be updated; you can select its details from the conflict result.
      Keep track of the IDs assigned to the process history item to perform subsequent update and delete operations.
      MutationVariablesSuccess resultConflict result
      mutation ($input: CreateCandidateProcessHistoryItemInput!) {
        createCandidateProcessHistoryItem(input: $input) {
          ... on CreateCandidateProcessHistoryItemPayload_Success {
            candidateProcessHistoryItem {
              id {
                value
              }
            }
          }
      
      
          ... on CreateCandidateProcessHistoryItemPayload_Conflict {
            conflictingCandidateProcessHistoryItem {
              id {
                value
              }
            }
          }
        }
      }

      Update a candidate process history item

      The updateCandidateProcessHistoryItem mutation  replaces a candidate process history item in its entirety:
      MutationVariablesResult
      mutation ($input: UpdateCandidateProcessHistoryItemInput!) {
        updateCandidateProcessHistoryItem(input: $input) {
          candidateProcessHistoryItem {
            id {
              value
            }
          }
        }
      }

      Delete a candidate process history item

      The deleteCandidateProcessHistoryItem mutation  removes a candidate process history item from the candidate profile.
      MutationVariablesResult
      mutation ($input: DeleteCandidateProcessHistoryItemInput!) {
        deleteCandidateProcessHistoryItem(input: $input) {
          candidateProcessHistoryItem {
            id {
              value
            }
          }
        }
      }