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:
25 Dec 1999
SEEK
Hayden R sent an invite for Millennium Bug Squasher in Melbourne.
26 Jul 1999
Partner
Terry A added a note: “Candidate not currently looking for work, try again in six months. Keen to stay in Melbourne.”
10 Jul 1998
SEEK
Robin R sent a message: “Hi Jessie, just wondering if you’d be interested in a Product Manager role based in Brisbane. Robin R, Product Manager, SEEK Limited”
07 Jul 1998
SEEK
Max C downloaded a CV.
Partner
Jean W logged a call for Product Manager in Brisbane.

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",
    "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": {
        "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 description and one of the following codes:
    Code
    Description
    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

Placement information

An interaction may be scoped to a given opportunity by providing the associated position profile:
JSON
Copy
{
  "action": {
    "code": "CandidateWorkflowTransition",
    "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
    Description
    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
    Description
    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 hiring organization.
To avoid unintentional duplication of data, SEEK enforces uniqueness on a partner-provided idempotencyId. A request to create an existing item will receive an 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
      }
    }
  }
}
Proactive Sourcing
Migration guides
Migration guides