Overview
Understanding the fundamentals of creating candidates will streamline your hiring process and ensure that you can efficiently manage your recruitment efforts.
This guide aims to provide a comprehensive guide to help you seamlessly integrate candidate posting into your existing jobs.
Posting a candidate to a live job
Step 1: Prepare the API Endpoint
To post a candidate, you need to know the specific API endpoint provided by the Occupop API. Typically, it would look something like this:
POST <https://api.occupop.com/rest/jobs/{job_uuid}/candidates> Replace {job_uuid} with the actual Job UUID where you want to post the candidate.
Step 2: Construct the JSON Payload
You need to construct a JSON payload with the candidate information. Below is an example of what the JSON payload might look like:
{
"email": "user@example.com",
"first_name": "string",
"last_name": "string",
"landline": "string",
"linkedin": "string",
"profile": "string",
"location_city": "string",
"location_state": "string",
"location_country": "string",
"source": "string",
"file_name": "string",
"file_url": "string"
}
Step 3: Collect data from HTML form and make the API request
Here is an example of how you can use an HTML form to collect candidate information and then post it to the Occupop API using JavaScript Fetch.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Post Candidate</title>
</head>
<body>
<form id="candidateForm">
<label for="firstName">First Name:</label>
<input type="text" id="firstName" name="firstName" required>
<label for="lastName">Last Name:</label>
<input type="text" id="lastName" name="lastName" required>
<label for="email">Email:</label>
<input type="email" id="email" name="email" required>
<label for="landline">Phone:</label>
<input type="tel" id="landline" name="landline" required>
<label for="city">City:</label>
<input type="tel" id="city" name="city" required>
<label for="state">State:</label>
<input type="tel" id="state" name="state" required>
<label for="country">Country (acronym only):</label>
<input type="tel" id="country" name="country" required>
<label for="linkedin">Linkedin URL:</label>
<input type="url" id="linkedin" name="linkedin" required>
<label for="coverLetter">Cover Letter:</label>
<textarea id="profile" name="profile" required></textarea>
<label for="resume">Resume file (PDF or DOC, Max,: 50Mb):</label>
<input type="file" id="resume" name="resume" required>
<input type="submit" value="Submit">
</form>
<script>
const token = 'your-public-or-private-token-here'
const apiUrl = '<http://api.occupop.com/rest/jobs>'
let job = {} // job object will receive data from API
fetch(apiUrl, { headers: { Authorization: token } })
.then(response => job = response.data[0])
const form = document.getElementById('candidateForm')
form.addEventListener('submit', event => {
event.preventDefault()
// befor all, organize data for requests...
const data = {
first_name: document.getElementById('firstName').value,
last_name: document.getElementById('lastName').value,
email: document.getElementById('email').value,
landline: document.getElementById('landline').value,
linkedin: document.getElementById('linkedin').value,
profile: document.getElementById('profile').value,
location_city: document.getElementById('city').value,
location_state: document.getElementById('state').value,
location_country: document.getElementById('country').value,
source: 'Acme SA Website',
file_name: document.getElementById('resume')[0].name,
file_url: job.cv_upload_signed_url.split('?')[0]
}
// first, upload the resume file to our storage service...
fetch(job.cv_upload_signed_url, {
method: 'PUT',
body: document.getElementById('resume')[0]
}).then(() => {
// ... then, create the CV resource in out API
fetch('<https://api.occupop.com/jobs/>' + job.id + '/candidates', {
method: 'POST',
headers: { Authorization: token },
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => {
alert('Candidate posted successfully!')
})
.catch(error => {
alert('An error occurred while posting the candidate.')
})
})
})
</script>
</body>
</html>
Make sure to add a public token to your request and handle the job you want to send correctly (in the example, we are using the first from the list).
If you want to use a private token, you can, but make sure that the token is accessible only internally on a web server or in a private request.
Step 4: Handle the Response
After making the request, handle the response from the API. A successful request will typically return a status code of 201 (Created) along with the details of the created candidate. If there are any errors, the API will return an appropriate status code and error message.
A successful response might look like this:
{
"data": {
"id": "string",
"job_uuid": "string",
"uuid": "string",
"status": "string",
"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"profile": "string",
"source_type": "string",
"source_name": "string",
"location": {
"city": "string",
"state": "string",
"country": "string",
"city_id": "string",
"city_full_name": "string",
"city_lat": "string",
"city_lng": "string",
"country_short": "string"
},
"file": {
"name": "string",
"url": "string"
},
"hiring_flow_step": {
"uuid": "string",
"name": "string"
},
"total_score": 0,
"ai_score": 0,
"interview_score": 0,
"questions_score": 0,
"questions_form": {
"type": "string",
"text": "string",
"options": "string",
"answer": "string"
},
"created_at": "string",
"updated_at": "string",
"received_at": "string",
"hired_at": "string",
"starts_at": "string"
}
}
Conclusion
By following these steps, you should be able to post a job candidate through the Occupop API successfully and collect candidates directly from your website or custom system.