How to get access / Authentication
To PATCH (edit) jobs onto one of our job boards, you will need a “username” and “password” which should be provided by our Sales Support team. This is the same username/password used for Posting the job.
The username/password MUST be linked to the same company as the company the job was posted for. For example, if you POST a job for s1jobs using username “s1jobsUsername” and password “s1jobsPass” but then PATCH (edit) the same job using a different username/password that is connected to “The Hearld Newspaper” then it will fail with the following error.
{
"_status": "ERR",
"_error": {
"message": "User is not allowed to post this job for this company. Speak to your admin.",
"code": 403
}
}
URL
The request must be a PATCH request with the URL:
recruiter.x1jobs.com/api/job/<job_id>
In the Headers, you must send Content-Type of application/json and the Body should be JSON. The key/values for the Body will be provided later on in this document. You MUST also send the jobs Etag in the Headers with the key “If-Match” and the value being the Etag.
The <job_id> at the end of the URL must be replaced with the job id of the job getting PATCHed.
Error Handling
Our system will return standard error messages. A standard error message to be returned is:
{
"_status": "ERR",
"_error": {
"message": "username and/or password incorrect or not provided2",
"code": 403
}
}
As you can see, the code is provided along with the message of what has went wrong.
If you provide the incorrect Etag, the system will return a more generic 428 error message like so:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>428 Precondition Required</title>
<h1>Precondition Required</h1>
<p>Client and server etags do not match</p>
PATCH Data - Required
| Key | Type | Comment |
| username | String | This will be provided by our Sales support team. This is the same as the API key. |
| password | String | This is the same as the API value. |
PATCH Data - Optional
If the following are not sent, no default will be used.
| Key | Type | Comment |
| job_description | Text | This can be sent in HTML if the data needs to be formatted |
| closing_date | Datetime | This can be used if you want to close the job earlier than 28 days. It will close in the morning of the date sent. |
| hours | String | “Full”, “Part” |
| salary_low OR/AND salary_high | Int | You can send any number here. If the number has a decimal point in it (e.g. 7.50) we round this (8). If you wish to keep 7.50, you can also send salary_text which is documented in the below. |
| salary_rate | String | “hourly”, “daily”, “weekly”, “yearly”, “monthly” |
| salary_text | String | This will be the salary on display to the jobseeker. For example, if you don’t want to jobseeker to know the salary, then you can send this with “negotiable”. If you also want to use decimals, you can also send “£8.50” here. |
| contract_type | String | “Contract”, “Permanent”, “Temporary” |
| apprenticeship | Boolean |
|
| graduate_suitable | Boolean |
|
| immediate_start | Boolean |
|
| external_reference | String | This will display on the job advert page as the ‘Job Ref No’ |
| job_working_location | String | This can be used to indicate if a job is remote, hybrid, onsite or home working. The following can be sent: 1. “Home working” 2. “Hybrid working” 3. “Remote working” 4. “Onsite working” |
| youtube_video_url | String | This must be a youtube URL. Go to your youtube video, click ‘Share’ and copy the link here. This is the link you need, not the URL in the browser. |
One of the following can also be PATCHed
* Only send 1
| Key | Type | Comment |
| apply_url | String | This will be a jumplink. |
| apply_email | String | This will allow the jobseeker to use our application form on x1jobs. |
| apply_phone_number | String | This will display the phone number on the job advert page. |
Data Types
| Type | Length/Format/Comments |
| String | 255 characters max. |
| Text | 60,000 characters max. |
| Int | Decimals will be rounded. |
| Date | YYYY-MM-DD |
| Boolean | 1/0 |
Response
You will get the following response on a successful PATCH. You should store the job id (id) and _etag so that you can continue PATCHing in the future. If you do lose this data, you can use the GET endpoint to receive it. The GET endpoint is documented in another file.
{
"href": "http://recruiter.x1jobs.com/api/job/25682733",
"_etag": "9331007f2b9e419fbb53af29da7ac5a6",
"canonical_url": "https://www.s1jobs.com/job/title-test-25682733",
"id": 25682733
}
As you can see from the response, you will get an href url which can be used in a GET endpoint to all the details about the job. The canonical URL is used to see the job on the website. The id is the job id.