When an update is made to the status of a relevant application or position,
send a signal with the following details:Some examples in this section—including the code sample above—are based on application status updates.
The data structure and modelling guidance are transferable to position status updates,
with detailed breakdowns of scenarios covered later in application signals and position signals.Consider a simple example of a recruitment process with a flat list of application statuses.
The list below is interactive:This state is modelled in the SEEK API like so:Our data structure is flexible and allows any status to be modelled.
Pass through statuses in each recruitment process as-is,
even if the process is fully customisable by the hirer.
Do not map or roll up the statuses to an abstracted intermediary representation.This design was chosen to avoid point-in-time mappings in your software that could fall out of date and require rework.
Mapping concerns are handled internally by SEEK,
and when we update our models moving forward,
we will internally reprocess captured signal data instead of requiring your software to backfill historical signals.The Provide a best approximation of ordering if your software models recruitment processes as a graph, where statuses are not strictly sequential.
For example, the application status list above contains the following non-sequential statuses:This state is modelled in the SEEK API like so:The SEEK API only supports two levels of hierarchy (
If the recruitment process is still in progress,
you must pass
- The type of signal, e.g.
ApplicationStatusUpdateorPositionStatusUpdate - Appropriate correlating identifiers
- The
currentstate of the application or position in the recruitment process - The
previousstate of the application or position, if convenient
ApplicationStatusUpdate sample in the SEEK API:MutationVariables
CopyGraphQL Explorer
{"input": {
// The type of signal.
"typeCode": "ApplicationStatusUpdate",
// The identifier to correlate the signal back to SEEK job ad or Apply with SEEK redirection.
"token": "globalPublicTest-WfRFAhG25YC8ADe3QvxAVz",
// The identifiers to correlate the signal back to SEEK job ads.
"positionProfileIds": "seekAnzPublicTest:positionProfile:jobAd:27cuZeA47",
// The current state of the application.
"current": {
// The overarching phase that the status corresponds to.
// Omit `phase` if your software does not support hierarchies.
"phase": {
// The free-text label of the phase as seen by the end user.
"label": "Hired",
// The relative place of the phase in the overall process.
"index": 5,
// The total number of phases in the process.
"total": 7
},
// The underlying granular status of the application.
"status": {
// The free-text label of the status as seen by the end user.
"label": "Hired",
// The relative place of the status in the overall process.
"index": 11,
// The total number of statuses in the process.
"total": 14
},
// Whether the candidate was placed in the position.
// Set to `null` for non-final statuses like `Interview`.
"success": true,
// When the current state took effect.
"timestamp": "2020-01-02T00:00:00.000Z"
},
// The previous state of the application.
// Omit `previous` if your software does not track prior states.
"previous": {
"phase": {
"label": "Offer",
"index": 4,
"total": 7
},
"status": {
"label": "Offer accepted",
"index": 8,
"total": 14
},
"success": null,
"timestamp": "2020-01-01T00:00:00.000Z"
}
}
}index and total indicate the relative place of the status in the recruitment process and may be used to infer coarse progression.
1-based indexing is recommended so that the last status in the recruitment process has an index that matches the total:JSON
Copy
{"index": 42,
"total": 42
}- Hired for a candidate that was placed in the position
- Talent pool for a candidate that was not successfully placed but is being considered for future positions
Interview status group with underlying statuses like First interview:phase and status).
If your software models more than two levels,
map the two most specific levels.The interactive examples above include statuses that are annotated with ticks and crosses .
These represent final or end states of the recruitment process.
For example, moving an application to Offer declined indicates that the candidate is no longer being considered for the position.Indicate whether a status is final with the success field in the SEEK API:success value | Final status? | Example usage in application status updates | Example usage in position status updates |
|---|---|---|---|
true | Candidate has been placed in the position | Position has been filled, either with a SEEK candidate or non-SEEK candidate | |
false | Candidate was not placed in the position, e.g. Offer declined | Position was closed without being filled, e.g. Withdrawn | |
null | Any non-final status, e.g. First interview | Any non-final status, e.g. Review |
null instead of false.Note that false does not imply that the candidate was unsuitable for the position;
the table above provides an example where the candidate declines the offer.In some scenarios, it may be hard to definitively mark the successful completion of a recruitment process.
For example,
a hirer may optimistically place candidates in a position,
then retroactively rely on probation periods to determine if they are the right fit.
For the practical purposes of Selection Signals,
pass true when the candidate has been hired into the position,
even if there are subsequent steps like onboarding & probation beyond that point.Signals must include identifiers that correlate them back to applications and/or positions on SEEK.
We support identifiers that your software already receives from other SEEK API use cases, such as:candidateApplicationProfileIdfrom Optimised ApplypositionProfileIdfrom Job Posting or Optimised Applyseek-tokenfrom linking out or Apply with SEEK