Tutorial 1 - Creating a Job
We will give a short introduction to usage of our ATS-API by providing a tutorial in which we:
Create and preview a job
Publish the previously created job
We will demonstrate how to create and update a job using TypeScript.
1. Create and preview a job
The /job/createOrUpdateJob endpoint allows you to create a new job listing or update an existing one. To use this endpoint, you need to provide the appropriate access_token obtained from the authentication process.
To Add a job, we use the createOrUpdateJob operation which will post an object to create a job. To preview the job before publishing, the isPublished property must be set to false (default). In this case the server will return a job object containing a previewUrl.
As seen in the Swagger Definition, the createOrUpdateJob endpoint requires two data:
sourceId: string
a unique identifier to this job (see details in Reference: job # sourceId)params: IJobAtsEditFields
the job details (see details in Reference: job # params)
(For complete documentation of the endpoint, please refer to the Swagger Definition that is auto-generated and up-to-date!)
TypeScript example:
Here's an example of how to create or update a job using TypeScript and node-fetch:
const { access_token } = await authenticate();
async function createOrUpdateJob(): Promise<void> {
const apiUrl = 'https://hokify.com/ats-api/job/createOrUpdateJob';
const headers = {
Authorization: `Bearer ${access_token}`,
'Content-Type': 'application/json'
};
const jobData = {
sourceId: 'hy13720954',
params: {
name: 'Typescript Developer (Focus Backend)',
company: 'hokify GmbH',
descriptionHTML: `
<p>We are looking for a backend enthusiastic Javascript developer who is willing to contribute to the further development of hokify. You are in direct contact with the management, project managers and all other developers.</p>
<p>hokify is the largest mobile job platform in Austria. Our mission is: We put good people into good jobs in the fastest, easiest and the most enjoyable way.</p>
`,
contactEmail: 'api@hokify.com',
type: '55d74e5d365315e629446d54', // Full time
region: 'at',
address: 'Jakov-Lind-Straße 2, 1020 Wien',
wage: 'min. 3.500 EUR',
fields: [
'56e05efd14fcd6fe094b443a' // Software development
]
}
} satisfies IAPICreateOrUpdateJobDTO;
try {
const response = await fetch(apiUrl, {
method: 'PUT',
headers,
body: JSON.stringify(jobData)
});
if (response.ok) {
const responseData = await response.json();
console.log('Job created/updated', responseData.job._id);
console.log('Job preview URL', responseData.job.webPreviewUrl);
} else {
console.error('Failed to create/update job');
}
} catch (error) {
console.error('Error:', error);
}
}
On success, the response also contains the webPreviewUrl to view the job to check the contents.
(Note that because we created the job without the isPublished param, which will default to false. However, we can still preview the job even if it is not publicly available to the users yet.)
2. Publish the previously created job
To finally publish the job, the isPublished param is set to true.
TypeScript example:
async function publishJob(): Promise<void> {
const apiUrl = 'https://hokify.com/ats-api/job/createOrUpdateJob';
const headers = {
Authorization: `Bearer ${access_token}`,
'Content-Type': 'application/json'
};
const jobData = {
sourceId: 'hy13720954',
params: {
isPublished: true
}
} satisfies IAPICreateOrUpdateJobDTO;
try {
const response = await fetch(apiUrl, {
method: 'PUT',
headers,
body: JSON.stringify(jobData)
});
if (response.ok) {
const responseData = await response.json();
console.log('Published job response', responseData);
} else {
console.error('Failed to create/update job');
}
} catch (error) {
console.error('Error:', error);
}
}
Which would result in a response output like:
Published job response {
success: true,
msg: 'job saved',
job: {
_id: '636b5e00a1b2c3d4e5f6789a',
jobNr: 194256,
name: 'Typescript Developer (Focus Backend)',
// [...]
webUrl: 'https://hokify.at/job/17486607',
// [...]
},
modified: false,
created: false,
warnings: []
}
(Note that there is no webPreviewUrl any more, but only the final webUrl of the published job.)