Development & debugging

Development & debugging

Development process

SEEK recommends a five stage process for developing software against the SEEK API. This reflects the process we use internally for developing new features:
  1. Review this documentation and the SEEK API Terms of Use to understand the concepts of the SEEK API and the scope of integrating it with your software.
  2. Request Playground and Developer Dashboard credentials from SEEK.
    Your Playground client credentials will give you limited permissions to the SEEK API’s read-only mock data. Use them to test accessing the SEEK API and mapping its data structures. While you can test the input validation of mutations with these credentials, the SEEK API will ultimately forbid requests to mutate our read-only mock data.
    The Developer Dashboard will give you a view of your live hirer relationships and events. This will give you visibility on your production SEEK API access before requesting your partner credentials.
  3. Request your final partner credentials from SEEK to access live production data. For partners with existing legacy integrations this will give you access to your existing SEEK hirer relationships.
    At the same time SEEK will add a relationship between your partner account and an unsearchable SEEK test hirer. Test hirers can export candidate applications and post job ads free of charge, but their job ads don’t appear in SEEK’s search results. This should be sufficient to test your software end-to-end against the SEEK API.
  4. Make a plan with SEEK to roll out your change to production hirers. There may be additional considerations for switching over from a legacy integration already in production.
  5. SEEK will remove the relationship between your partner account and the test hirer when it’s no longer needed. The test hirer will be returned to a pool to be reallocated to another partner.
These steps can be repeated at any time as required.
It’s recommended that you continue to use your Playground credentials for exploratory testing as your partner credentials are highly sensitive.

Tracing requests

When an issue is found with an integration it’s sometimes difficult to determine which services were involved and how they interacted. SEEK has conventions for additional HTTP request headers to help trace issues across both our systems. These conventions should be used for all server-to-server HTTP requests including GraphQL queries, token requests and attachment file downloads.
  • User-Agent is a standard HTTP header identifying the service making an HTTP request. While your HTTP client library likely already sends a generic User-Agent, it’s recommended that you override this to include the name and version of the service making the request. This makes it easier to trace a request back to a specific deployment of your software when debugging an issue.
  • The X-Request-Id header is a SEEK extension for tracing a request as it passes through our systems. It’s recommended that you generate a UUID for each HTTP request and record that UUID along with any relevant log entries.
  • The X-Session-Id header is a SEEK extension for grouping requests in the same interaction together. This helps isolate the sequence of events that led to an issue or error, especially for high traffic integrations.
    You can choose which definition of session makes the most sense for you. For example, an interactive user flow for creating & posting a job ad might be assigned a single session. Or, every time your webhook endpoint is called you might generate a new session for all HTTP requests related to processing its events.
    It’s recommended that you generate a UUID for each session and record that UUID along with any relevant log entries.

Example request

POST /graphql HTTP/1.1
User-Agent: example-application-import-webhook/1.2.3
X-Request-Id: 749fbdc9-fbe5-40e9-b5ae-fee3375f1e28
X-Session-Id: 6eb0559a-cb91-4178-bb3d-9f5513e9ecc2