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

• Sample API Client
• Walkthrough Managing an Advertisement
• Retrieve an Access Token
• Retrieving API Links
• Create an Advertisement
• Errors
• Common Error Response Content
• Update an Advertisement
• Expire an Advertisement
• Get an Advertisement
• Get All Advertisements

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.

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.

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.

• Create a Job Advertisement by sending a POST request with advertisement type Classic
• Method: POST
Copy

1
2
3
4
5
6
{
  "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
Copy

1
2
3
4
5
6
7
{
  "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

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.

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.

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.
This is only required for testing and is not necessary in production.An example of missing fields:
1. The request contains
Copy

1
2
3
4
5
6
7
{
    "location":
        {
            "id": "EuropeRussia",
            "area": "RussiaEasternEurope"
        }
}

2. The response contains
Copy

1
2
3
4
5
6
{
    "location":
        {
            "id": "EuropeRussia"
        }
}

3. The location.area was ignored because the field name should have been areaId, not area.
7. Fields that allow formatting tags (e.g. the advertisement details) only permit specific formatting tags. See the “Formatting” 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. theself link of the resource.

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.

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.

 HTTP/1.1 403 Forbidden Content-Type:application/vnd.seek.advertisement-error+json; charset=utf-8; version=1

HTTP/1.1 400 Bad RequestContent-Type: application/vnd.seek.advertisement-error+json;charset=utf-8; version=1

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.

HTTP/1.1 422 Unprocessable EntityContent-Type: application/vnd.seek.advertisement-error+json;charset=utf-8; version=1

HTTP/1.1 409 ConflictLocation: https://{host}/advertisement/{advertisementId}

• 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.

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.
This is only required for testing and is not necessary in production. An example of missing fields:
1. The request contains
   Copy

   1
   2
   3
   4
   5
   6
   7
   {
       "location":
       {
           "id": "EuropeRussia",
           "area": "RussiaEasternEurope"
       }
   }

2. The response contains
   Copy

   1
   2
   3
   4
   5
   6
   {
       "location":
       {
           "id": "EuropeRussia"
       }
   }

3. The location.area was ignored because the field name should have beenareaId , not area .
6. Fields that allow formatting tags (e.g. the advertisement details) only permit specific formatting tags. See theFormatting tab for more information.
7. 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.

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.

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.
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).

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.

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.