Docs  Selection Signals  Sending signals
  • No results found

Sending signals

The worked examples documented up to this point already represent signals in the data structure accepted by the sendSignal and sendSignals mutations.When implementing signal capture in your software, you will need to make two related design decisions:
  1. Whether to send signals in near real time or on a periodic interval
  2. Whether to send signals individually or in batches

Real time vs periodic interval

We recommend implementing an event-based system in your software to trigger signal capture from status changes in near real time. You may debounce  user input to merge updates made in quick succession, and to cancel out misclicks and similar mistakes.If your software has constraints that prevent such a design, send signals in batches periodically, with a maximum interval of 24 hours. Each signal must:
  1. Include a timestamp that represents when the status update actually occurred in your softwareIt must not represent when the status update was sent to SEEK at the end of the period.
    Event
    Timestamp
    Use as signal timestamp?
    Hirer moves application to Shortlist status
    2020-01-01T09:00:00.000Z
    Partner synchronises application status updates for the past 24 hours
    2020-01-02T00:00:00.000Z
  2. Represent a granular update that actually occurred in your softwareIt must not represent a status that has been rolled up, beyond rudimentary debouncing of user input occurring within seconds of each other. For example, if the following events occur in a given period:
    Event
    Timestamp
    Send as independent signal?
    Hirer moves application to Shortlist status
    2020-01-01T09:00:00.000Z
    Hirer moves application to Phone screen status
    2020-01-01T10:00:00.000Z
    Hirer moves application to First interview status
    2020-01-01T17:00:00.000Z
    At the end of the period, your software must send all three status updates, not just the final status of First interview.Your software is also forbidden from simply resending the statuses of all relevant applications and positions at each interval; a status update must only be sent if the status actually changed within the period.

Individual vs batched

While most of our code samples use the individual sendSignal mutation for simplicity, any of the documented signals can be batched together in a sendSignals mutation.As a general rule, use the batch sendSignals mutation if your software may send more than one signal at a time, including if it:
  • Sends signals on a periodic interval rather than in near real time
  • May trigger multiple status updates at once (e.g. due to process automation)
  • Supports resending historical data (e.g. to correct data quality issues)
MutationVariables
CopyGraphQL Explorer
{
  "input": {
    "signals": [
      {
        "typeCode": "ApplicationStatusUpdate",
        "token": "globalPublicTest-WfRFAhG25YC8ADe3QvxAVz",
        "current": {
          "status": {
            "label": "Successful",
            "index": 11,
            "total": 14
          },
          "success": true,
          "timestamp": "2020-01-02T00:00:00.000Z",
          "phase": {
            "label": "HIRED",
            "index": 5,
            "total": 7
          }
        },
        "previous": {
          "status": {
            "label": "Accepted",
            "index": 7,
            "total": 14
          },
          "success": null,
          "timestamp": "2020-01-01T00:00:00.000Z",
          "phase": {
            "label": "OFFER",
            "index": 4,
            "total": 7
          }
        }
      },
      {
        "typeCode": "PositionStatusUpdate",
        "positionProfileIds": "seekAnzPublicTest:positionProfile:jobAd:27cuZeA47",
        "current": {
          "status": {
            "label": "Withdrawn",
            "index": 6,
            "total": 6
          },
          "success": false,
          "timestamp": "2020-01-02T00:00:00.000Z",
          "phase": {
            "label": "CLOSED",
            "index": 4,
            "total": 4
          }
        },
        "previous": {
          "status": {
            "label": "Review",
            "index": 4,
            "total": 6
          },
          "success": null,
          "timestamp": "2020-01-01T00:00:00.000Z",
          "phase": {
            "label": "OPEN",
            "index": 3,
            "total": 4
          }
        }
      }
    ]
  }
}
Up to 100 signals can be included in one sendSignals operation. If you have more than 100 signals to send, split them into chunks of 100 and run multiple operations, monitoring the SEEK API responses for rate limiting errors.

Data lifecycle

Selection signal data remains valid for 180 days from the time of generation. The relevant identifiers are different for different signal types, however the records they relate to will all remain valid for a 180 day lifecycle.The identifiers for the different signal types are:
Signal type
Identifier(s)
Expiry time
Application complete for external applications
token
180 days after the token is generated
Application status update for external applications
token, positionProfileIds
180 days after the token is generated
Application status update for Optimised Apply
candidateApplicationProfileId
180 days after the candidate application is created
Position status update
positionProfileIds
180 days after the position profile is posted
Should an expired record be provided in the sendSignal or sendSignals mutation, the SEEK API will internally handle the error and no error message will be returned.

Troubleshooting

The sendSignal and sendSignals mutations will return errors consistent with our documented GraphQL error responses. If your software receives authentication or transient server errors, it must retry sending of signals until successful. Ensure you have monitoring in place to detect and alert on errors when sending signals, to ensure there are no gaps in data. Take particular care with rate limiting errors if your software may send a large number of signals in quick succession.A BAD_USER_INPUT error may occur if there is a structural issue with the token. Ensure that the token exactly matches the seek-token that was received from the redirect.We recommend that you log full requests and responses to the sendSignal and sendSignals mutations during development to facilitate debugging. Use a unique X-Request-Id for each request to assist in support investigations; see our guidance on tracing requests for more information.
Selection Signals: Position signals
How-to guides: Overview