Docs  Selection Signals  Data structure
  • No results found

Data structure

Status updates

When an update is made to the status of a relevant application or position, send a signal with the following details:
  1. The type of signal, e.g. ApplicationStatusUpdate or PositionStatusUpdate
  2. Appropriate correlating identifiers
  3. The current state of the application or position in the recruitment process
  4. The previous state of the application or position, if convenient
In practice, this looks like the following 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"
    }
  }
}
Some examples in this section—including the code sample above—are based on application status updates. The data structure and modelling guidance should be transferable to position status updates, with detailed breakdowns of scenarios covered later in application signals and position signals.

Mapping statuses

Consider a simple example of a recruitment process with a flat list of application statuses. The list below is interactive:
This state is represented in the SEEK API like so:
{
  "status": {
    "label": "First interview",
    "index": 4,
    "total": 14
  },
  "success": null,
  "timestamp": "2025-05-22T23:42:06.261Z"
}
The SEEK API does not have a fixed set of statuses that it supports. Instead, pass through updates for all statuses in the recruitment process, even if the process is fully customisable by the hirer.Our data structure is generic and allows any status to be represented. 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 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
}
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:
  1. Hired for a candidate that was placed in the position
  2. Talent pool for a candidate that was not successfully placed but is being considered for future positions

Hierarchical statuses

Your software may support a grouping or hierarchy of statuses. The interactive example below includes an Interview status group with underlying statuses like First interview:
This state is represented in the SEEK API like so:
{
  "phase": {
    "label": "Interview",
    "index": 3,
    "total": 7
  },
  "status": {
    "label": "First interview",
    "index": 4,
    "total": 14
  },
  "success": null,
  "timestamp": "2025-05-22T23:42:06.274Z"
}
The SEEK API only supports two levels of hierarchy (phase and status). If your software models more than two levels, map the two most specific levels.

Final statuses

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
If the recruitment process is still in progress, you must pass 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.

Correlating identifiers

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:All such identifiers must be passed in the exact format that they were received, with no additional encoding nor whitespace.The accepted & required identifiers differ by signal type. They are detailed further in application signals and position signals below.
Use cases: Selection Signals
Selection Signals: Application signals