SEEK - Australia's no. 1 jobs, employment, career and recruitment site

Job Posting
Sample API ClientA NuGet package is available containing a .NET client for the Job Ad Posting API. The source code for this API client and an example console application that uses the .NET client can be found on GitHub.Sample inputs and responses for common use cases can be found in the PACTs folder.
Managing an AdvertisementThis is an example flow that shows how to use the API.All date-time inputs and outputs are always in UTC and formatted as yyyy-MM-ddTHH:mm:ssZ e.g. 2015-11-06T21:19:00ZPlease read all the documentation for usage notes and development testing recommendations.Creating an Advertisement
  1. Retrieve an Access Token (if your current access token has not expired).
  2. Retrieve API Links.
  3. Use the “Advertisement” link template from the response in (2) to generate a URI for creating an advertisement.
  4. Create an Advertisement by sending a POST request to the URI generated in (3). See the “Create an Advertisement” section below for usage notes and development testing recommendations.
  5. The response code indicates if the request succeeded or failed.
  6. The content of a successful response will contain an ID and a “self” link in addition to the advertisement that was created.
  7. A failed request may contain information indicating the reason for the failure. See the “Errors” section below for more information.
Updating an Advertisement
  1. Retrieve an Access Token (if your current access token has not expired).
  2. Retrieve API Links.
  3. Use the “Advertisement” link template from the response in (2) and the advertisement ID obtained when the advertisement was created to generate a URI for updating the advertisement.
  4. Update the advertisement by sending a PUT request to the URI generated in (3). See the “Update an Advertisement” section below for usage notes and development testing recommendations.
  5. The response code indicates if the request succeeded or failed.
  6. The content of a successful response will contain the advertisement that was updated.
  7. A failed request may contain information indicating the reason for the failure.
Expiring an AdvertisementSEEK expires advertisements automatically 30 days after creation. This means that a programmatic request to expire an advertisement is only needed if the position was filled sooner than 30 days.
  1. Retrieve an Access Token (if your current access token has not expired).
  2. Retrieve API Links.
  3. Use the “Advertisement” link template from the response in (2) and the advertisement ID obtained when the advertisement was created to generate a URI for expiring the advertisement.
  4. Expire the advertisement by sending a PATCH request to the URI generated in (3). See the “Expire an Advertisement” section below for usage notes and development testing recommendations.
  5. The response code indicates if the request succeeded or failed.
  6. The content of a successful response will contain the advertisement that was expired.
  7. A failed request may contain information indicating the reason for the failure.
Mandatory StandOut Contract Behaviour
  • Create a Job Advertisement by sending a POST request with advertisement type Classic
    • Method: POST
    1
    2
    3
    4
    5
    6
    7
    {
        "thirdParties" :
            {
            "advertiserId" : "1234",
            },
        "advertisementType" : "Classic"
    }
  • Job Posting API successfully validates the advertisement and automatically updates the advertisement type from Classic to StandOut and returns a 200 – OK status response and the advertisement id.
    • Status: 200
    1
    2
    3
    4
    5
    6
    7
    8
    {
        "id": "{advertisementId}",
        "thirdParties":
        {
            "advertiserId": "1234"
        },
        "advertisementType": "StandOut"
    }
  • The caller to compare the advertisementType field to determine if the advertisement type was upgraded automatically
  • The caller should then handle the above by updating the existing Job Ad advertisement type in your system, so the client can now see their Job Ad advertisement type is StandOut
    • The caller should not repost the updated job ad back to an advertisement type Classic
Retrieve an Access TokenAn OAuth 2.0 access token is required to authorise calls made to the Job Ad Posting API. Use your OAuth2 credentials (a client key and secret provided by SEEK) to obtain an access token from the SEEK OAuth endpoint. The following diagram shows the conceptual sequence for obtaining the access token.Usage Notes
  1. See the SEEK OAuth 2 Apiary documentation for detailed instructions and sample code to use the API to retrieve an OAuth access token.
  2. Once your access token has expired, you will get 401 Unauthorised errors from all endpoints. At that time the access token should be refreshed.
  3. An alternate to this is to refresh your access token before it expires. See the OAuth documentation on Apiary for more information.
Retrieving API LinksThe following diagram shows the conceptual sequence for getting API links.Usage Notes
  1. It is highly recommended that the API consumer retrieve the API links prior to performing operations such as “Create Advertisement” or “Get All Advertisements” since the returned URI templates can change in the future. This should ensure the API consumer does not encounter errors when the URI templates change.
  2. These API links should not be stored by the API consumer as they may change.
Create an AdvertisementAdvertisements are created by sending a POST request to the advertisement endpoint. The following diagram shows the conceptual sequence for creating an advertisement. See the Apiary documentation for detailed instructions on all the API endpoints well as playground to test the API end points.Usage Notes
  1. Each job created must have a creation ID that is unique across all job advertisements that have been created, both open and expired, by the system (i.e. Recruitment Software, Agent or Advertiser).
  2. Posting a job with a duplicate creation ID will result in a 409 (conflict) response code being returned.
    1. This means the job with the given creation ID already exists and ensures that duplicate jobs are not created when POSTing the same job multiple times.
    2. The URL from the response location header should not be stored since it is an absolute URL. The advertisement’s self HAL link should be retrieved and stored instead by performing a GET request on the location URL.
  3. When the Job Posting API accepts the advertisement, a 200 response code is returned.
    1. The response content contains the accepted advertisement with the advertisement id and a self HAL link (a relative URI) to the advertisement.
    2. Either the advertisement’s id or self HAL link should be stored for performing future API operations such as “Get Advertisement”, “Update Advertisement”, “Expire Advertisement”, etc.
      1. The advertisement’s id can be used to build the appropriate relative URI using the “advertisement” URI template retrieved from the “API Links” endpoint.
      2. The advertisement’s self HAL link is a relative URI that can be used as is.
  4. All date-time inputs and outputs are always in UTC and formatted as yyyy-MM-ddTHH:mm:ssZ e.g. 2015-11-06T21:19:00Z
  5. In the request body, when “location” fields are use, the “granularLocation” fields should not be provided and vice versa.
  6. The caller should compare the advertisement sent in the request to the advertisement returned in the response. If there are any differences e.g. missing fields then it could indicate that the advertisement sent in the request contained fields that did not match expected fields and were therefore dropped by the API.
  7. This is only required for testing and is not necessary in production.An example of missing fields:
    1. The request contains
    2. 1
      2
      3
      4
      5
      6
      7
      {
          "location":
              {
                  "id": "EuropeRussia",
                  "area": "RussiaEasternEurope"
              }
      }
    3. The response contains
    4. 1
      2
      3
      4
      5
      6
      {
          "location":
              {
                  "id": "EuropeRussia"
              }
      }
    5. The location.area was ignored because the field name should have been areaId, not area.
  8. Fields that allow formatting tags (e.g. the advertisement details) only permit specific formatting tags. See the “Formatting” tab for more information.
  9. Additional properties may be returned in the response content. These are expected e.g. the _links block which contains HAL links e.g. theself link of the resource.
ErrorsHandling Response CodesThe API consumer should handle all errors, not only those specified in the API documentation. A good practice for handling 5XX response codes is to retry the request later using an exponential back-off timing strategy.Some common reasons that cause API errors are:
  1. No access token supplied with the request.
  2. Invalid or expired access token, or access token is not valid for the environment.
  3. Malformed or invalid JSON.
  4. There’s a problem with your SEEK account, e.g. your account does not permit you to perform the operation on behalf of the advertiser.
  5. Validation failed on the request content.
  6. Creating an advertisement but re-using acreationId.
  7. Attempting to manipulate advertisements that don’t exist.
Error Response Content FormatThe API may return information related to errors in the response content. The error response content has the following media type and structure:
Content-Type: application/vnd.seek.advertisement-error+json; charset=utf-8; version=1
1
2
3
4
5
6
7
8
{
    "message": "Overall Error Message",
    "errors": [{
      "field": "path.to.field[2].name",
      "code": "ErrorCode",
      "message": "Error message intended for developers."
    }]
}
  1. The top-levelmessage field contains the overall error message e.g. “Validation Failure”.
  2. The errors field is optional and when present contains an array of error items.
  3. Each error item:
    1. May have a field when the error relates to a specific field that was or should have been present in the request content. When the field name contains an index value, the index value is zero-based.
    2. Will have a code field with a value representing the error e.g. “MaxLengthExceeded”. This field value can be coded against since it should not change.
    3. Will have a messagefield containing a message intended for developers. This message should not be coded against as it may change. The message should not be shown to end-users since it could contain information like regular expressions which end users will not understand.
Common Error Response ContentThe API can return the following example error responses. Note that messages should not be coded against since they can change. See the Apiary documentation for all response codes and content.
When Request is Not AuthenticatedHTTP/1.1 401 Unauthorized
When API Operation is Not Permitted
HTTP/1.1 403 Forbidden Content-Type:application/vnd.seek.advertisement-error+json; charset=utf-8; version=1
The response content will have message and errors fields with the following codes:
Code
Message Example
AccountError
Contact SEEK
InvalidValue
Invalid value ‘something’ in field ‘advertiserId’
RelationshipError
Your account does not have a relationship with Advertiser ‘1234’
Unknown
No operations are permitted with supplied access token
When Request Content Contains Invalid JSON
HTTP/1.1 400 Bad RequestContent-Type: application/vnd.seek.advertisement-error+json;charset=utf-8; version=1
The response content will only have a message field indicating why the request content is invalid. Examples of error messages are:
  1. After parsing a value an unexpected character was encountered: j. Path ‘advertisementDetails’, line 1, position 26.
  2. Unexpected end when deserializing object. Path ‘template’, line 1, position 50.
  3. Error converting value “agentId”. Path ”, line 1, position 9.
When Request Content Contains Validation Errors
HTTP/1.1 422 Unprocessable EntityContent-Type: application/vnd.seek.advertisement-error+json;charset=utf-8; version=1
The response content will have message and errors fields. The error items may include the field field and should include the code and message fields.
CodeExample Field
Example Message
AlreadySpecifiedtemplate.items[2].name
The Name field value has been used more than once in the list.
ChangeNotAllowedadvertisementType
The advertisement type cannot be changed from StandOut to Classic.
InvalidEmailAddressapplicationEmail
The ApplicationEmail field is not a valid e-mail address.
InvalidFormatjobSummary
The JobSummary field does not allow any formatting tags. Text starting with the < symbol is interpreted as a formatting tag.
InvalidRequestContent
The request must contain content of type: ‘application/vnd.seek.advertisement+json; version=1’.
InvalidState
Advertisement has already expired.
InvalidUrlapplicationFormUrl
The ApplicationFormUrl field is not a valid fully-qualified
InvalidValuethirdParties.agentId
The AgentId field is not allowed.
MaxLengthExceededstandout.bullets[1]
The field Bullets[1] must be a string or array type with a maximum length of ‘3’.
RegexPatternNotMatchedvideo.url
The field Url must match the regular expression ‘actual regular expression would be here’
Requiredtemplate.items[1].name
The Name field is required.
ValueOutOfRangesalary.maximum
The field Maximum must be between 1 and 999999. Please note: MaxSalary must be within 2 bands of Min salary (eg 65,000-69,999 is ok but 65,000 to 84,999 is not). Please see expected values tab for the Valid Values spread sheet for more details
Do not retry the request automatically.The user needs to correct the validation errors before retrying the request.
When Creating an Advertisement with a CreationId that Already Exists
HTTP/1.1 409 ConflictLocation: https://{host}/advertisement/{advertisementId}
Where the location header contains the absolute URL of the existing advertisement.
When Performing an Operation on an Advertisement that Does Not ExistHTTP/1.1 404 Not Found
Job Advertisement Enhancements To ensure our hirers, integration partners and mutual clients are having the best experience with SEEK’s Job Posting API, and that Job Advertisements are being uploaded successfully to SEEK the first time they are posted, the Job Posting API has been enhanced to help support the following:
  • Automatically removing any invalid or unsupported HTML tags – Please review the formatting tab
  • Automatically removing any URL hyperlinks to display as text (only in the case where the advertiser is not allowed to use hyperlinks) – Please review the formatting tab
  • Automatically removing any invalid URL link and replacing with text: [link removed] – Please review the formatting tab
  • Automatically replacing the invalid maximum salary with a valid maximum salary that is within 2 bands of the minimum – Please review the Expected Values spreadsheet
  • Automatically swaps the minimum salary and maximum salary when the minimum salary is greater than the maximum salary – Please review the Expected Values spreadsheet
  • Automatically truncating the Job Summary character limit when exceeded and replacing the last 3 characters with an ellipsis (3 dots) – Please review the fields tab
  • SEEK has updated 8 Location Descriptions to be more relevant – Please review the Expected Values spreadsheet
  • If the create/update request succeeds (no validation failures), the response will contain the actual expiry date and time of the advertisement in UTC.
  • SEEK will no longer be supporting the ability to add or remove a screen once the job ad has been posted. This will make shortlisting of candidates easier as this will stop different candidates being compared against different criteria for the same role.
To avoid the automatic removal, it is highly recommended that our hirers, integration partners and mutual clients only provide SEEK with valid data.
Update an AdvertisementAdvertisements are updated by sending a PUT request to the advertisement’sself HAL link (obtained when the advertisement was created) or the URI generated by using the advertisement link template from the “Get API Links” response with the advertisement id.The following diagram shows the conceptual sequence for updating an advertisement.Usage Notes
  1. If a creation ID is provided in the request content, it will be ignored.
  2. When the Job Posting API accepts the advertisement, a 200 response code is returned.
    1. The response content contains the accepted advertisement.
  3. The caller should compare the advertisement sent in the request to the advertisement returned in the response.
  4. All date-time inputs and outputs are always in UTC and formatted as yyyy-MM-ddTHH:mm:ssZ e.g. 2015-11-06T21:19:00Z
  5. If there are any differences e.g. missing fields then it could indicate that the advertisement sent in the request contained fields that did not match expected fields and were therefore dropped by the API.
  6. This is only required for testing and is not necessary in production. An example of missing fields:
    1. The request contains
      1
      2
      3
      4
      5
      6
      7
      {
          "location":
          {
              "id": "EuropeRussia",
              "area": "RussiaEasternEurope"
          }
      }
    2. The response contains
      1
      2
      3
      4
      5
      6
      {
          "location":
          {
              "id": "EuropeRussia"
          }
      }
    3. The location.area was ignored because the field name should have beenareaId , not area .
  7. Fields that allow formatting tags (e.g. the advertisement details) only permit specific formatting tags. See theFormatting tab for more information.
  8. Additional properties may be returned in the response content. These are expected e.g. the _links block which contains HAL links e.g. the self link of the resource.
Expire an AdvertisementAdvertisements are expired by sending a PATCH request to the advertisement’s self HAL link (obtained when the advertisement was created) or the URI generated by using the advertisement link template from the “Get API Links” response with the advertisement id.Advertisements are expired 30 days after creation. This means advertisements only need to be expired if the position was filled sooner than 30 days.The request content follows the RFC-6902 standard for patching the advertisement.The following diagram shows the conceptual sequence for updating an advertisement.Usage Notes
  1. When the Job Posting API accepts the advertisement, a 200 response code is returned.
    1. The response content contains the accepted advertisement at the time of expiry.
    2. All date-time inputs and outputs are always in UTC and formatted as yyyy-MM-ddTHH:mm:ssZ e.g. 2015-11-06T21:19:00Z
  2. The advertisement cannot be updated, viewed or expired after the expire request has been accepted by the API.
Get an AdvertisementAn advertisement can be retrieved by sending a GET request to the advertisement’s self HAL link (obtained when the advertisement was created) or the URI generated by using the advertisement link template from the “Get API Links” response with the advertisement id.The following diagram shows the conceptual sequence for getting an advertisement.Usage Notes
  1. If the API consumer stored the advertisement ID instead of the advertisement’s self HAL link, the advertisement’s link can be built as follows:
    1. Get the API links.
    2. Use the advertisement HAL link template to build the relative resource URI.
    3. Use the constructed link in the GET request to the API host address.
    4. The advertisement link should not be created by the API consumer in any other way as this could result in issues if the API links change in the future.
  2. It is preferable to use the advertisement’s “self” HAL link obtained when the advertisement was created instead of constructing the resource link using hard-coded URI templates (i.e. not retrieving the link templates from the “API Links” response).
Get All AdvertisementsAll advertisements linked to the API consumer can be retrieved by sending a GET request to the advertisements HAL link returned when getting the API links.The following diagram shows the conceptual sequence for getting all advertisements.Usage Notes
  1. If the API consumer is a recruitment software provider or agent, the advertisements for a specific advertiser can be retrieved by providing the advertiserId parameter in the advertisers HAL link template. When the advertiserId parameter is omitted, all advertisements related to the API consumer are returned.
  2. The response:
    1. Contains a subset of the advertisements in the _embedded block where each advertisment only has summary information (e.g. the job title, the job reference where one exists, the advertisement’s HAL _linksblock, etc). A GET request on the advertisement’s self HAL link can be used to retrieve the full advertisement details.
    2. Is ordered from newest to oldest by creation date.
    3. Contains a HAL _links block with:
      1. A self HAL link to the current page.
      2. A next HAL link when there are more advertisements to retrieve.
The API consumer should handle:
  1. Only one page of results being returned (no next HAL link in the response content).
  2. Retrieving the next page of results by following the next HAL link in the response content.
  3. No advertisements being returned.