Build your careers site on Nova

This guide takes you from creating a key to sending an application from your own website. Every call goes from your server to Nova. Your page talks to your server, never to Nova.

This is the same answer as Nova's careers page

An application sent through the API is processed exactly like one sent from Nova's own careers page. Nova matches the candidate with the people already in your account, and that match can update an existing candidate and merge candidates. Send only data you are sure belongs to the person applying.

1. Create a key

In Nova, open Settings › API and create a key with the careers-site:apply permission. Copy the secret when it is shown: you cannot see it again. Store it in an environment variable of your server, as explained in Authentication and permissions.

2. List the published jobs

List the published jobs returns the jobs that are open for applications, page by page (see Pagination). You can filter by department, location, work model and work type. List the departments gives you the values for a department filter.

3. Read a job and its form

Read a published job returns the job with the application form it asks for and its questions. Build your form from that answer so it always asks what the job asks. A job that is not published answers 404 job_not_found.

4. Upload the files of file questions

If a question asks for a file, upload it first. The call returns the file id to use as the answer. Files can be pdf, doc or docx and up to 10 MB.

5. Send the application

Send an application with the contact fields, the answers and, if the job accepts them, the CV and the cover letter:

Node
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('firstName', 'Ada');
form.append('lastName', 'Lovelace');
form.append('email', 'ada@example.com');
form.append('answers', JSON.stringify([ { questionId: 7, answer: 'Yes' } ]));
form.append('cv', new Blob([ await readFile('cv.pdf') ]), 'cv.pdf');

const response = await fetch('https://api.novatalent.com/v1/careers/jobs/123/applications', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.NOVA_API_KEY },
  body: form,
});

if (response.status === 409) {
  console.log('This candidate already applied');
}
  • 201: the application is recorded.
  • 409 already_applied: this candidate already applied to this job.
  • 400: a field is missing or not valid. error.param says which one.
  • 429 rate_limited: wait for the seconds in Retry-After. A key can send 60 applications per minute.

Protect your own form against bots

Nova cannot tell a person from a bot: it only sees your server. Protect your form before you call Nova, with a CAPTCHA or an equivalent check, a hidden field that bots fill, and a limit of submissions per visitor. Otherwise a bot can fill your pipeline with false candidates and use up the applications budget of your key.