Skip to main content
POST
/
jobs
Create job
curl --request POST \
  --url https://api.instaview.sk/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Senior TypeScript Developer",
  "description": "We are looking for an experienced TypeScript developer...",
  "jobUrl": "https://company.com/careers/senior-typescript-dev",
  "benefits": "Health insurance, remote work, flexible hours",
  "requiredSkills": [
    "TypeScript",
    "React",
    "Node.js"
  ],
  "niceToHaveSkills": [
    "Docker",
    "AWS",
    "GraphQL"
  ],
  "languageRequirements": [
    {
      "language": "EN",
      "proficiency": "B2"
    },
    {
      "language": "SK",
      "proficiency": "C1"
    }
  ],
  "education": [
    "BACHELOR_LEVEL",
    "MASTER_LEVEL"
  ],
  "experience": "FIVE_TO_10_YEARS",
  "contractType": "FULL_TIME",
  "status": "OPEN",
  "location": {
    "workMode": "REMOTE",
    "street": "Hlavná 123",
    "city": "Bratislava",
    "postalCode": "81101",
    "countryCode": "SK"
  },
  "salary": {
    "min": 50000,
    "max": 80000,
    "currency": "USD",
    "period": "YEARLY"
  },
  "metadata": {
    "externalJobId": "JOB-12345",
    "department": "Engineering",
    "hiringManager": "Jane Doe"
  }
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "companyId": "987e6543-e21b-12d3-a456-426614174000",
  "title": "Senior TypeScript Developer",
  "status": "OPEN",
  "createdAt": "2024-11-16T10:30:00Z",
  "updatedAt": "2024-11-16T10:30:00Z",
  "description": "We are looking for an experienced TypeScript developer...",
  "jobUrl": "https://company.com/careers/senior-typescript-dev",
  "benefits": "Health insurance, remote work, flexible hours",
  "requiredSkills": [
    "TypeScript",
    "React",
    "Node.js"
  ],
  "niceToHaveSkills": [
    "Docker",
    "AWS"
  ],
  "languageRequirements": [
    {
      "language": "EN",
      "proficiency": "B2"
    },
    {
      "language": "SK",
      "proficiency": "C1"
    }
  ],
  "education": [
    "BACHELORS"
  ],
  "experience": "SENIOR",
  "contractType": "FULL_TIME",
  "location": {
    "workMode": "REMOTE",
    "street": "Hlavná 123",
    "city": "Bratislava",
    "postalCode": "81101",
    "countryCode": "SK"
  },
  "salary": {
    "min": 50000,
    "max": 80000,
    "currency": "USD",
    "period": "YEARLY"
  },
  "metadata": {
    "externalJobId": "JOB-12345",
    "department": "Engineering"
  }
}
Creates a new job posting scoped to the API key’s company. Jobs serve as containers for candidates and are required before creating candidates or scheduling interviews.

​
Overview

The create job endpoint allows you to add new job postings to your recruitment pipeline. Each job must include at minimum a title, description, and status. Jobs can be enhanced with skills requirements, location information, salary details, and more.

​
Use Cases

  • Job Posting Creation: Add new positions to your recruitment system
  • ATS Integration: Sync jobs from external ATS systems
  • Bulk Job Import: Import multiple job postings
  • Job Template Creation: Create job templates for recurring positions

​
Basic Job Creation

{
  "title": "Senior Software Engineer",
  "description": "We are seeking an experienced software engineer...",
  "requiredSkills": ["JavaScript", "React", "Node.js"],
  "status": "OPEN"
}

​
Company Scoping

Jobs are automatically scoped to your API key’s company. All candidates and interviews associated with a job must belong to the same company.

​
Status Management

Jobs start with a status (typically OPEN for active positions). You can update the status later using the Update Job endpoint.

Jobs Resource Guide

Comprehensive guide to job management, including skills, location, and salary configuration

Create Candidate

Add candidates to your jobs

List Jobs

View all your job postings

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
​
title
string
required

Job title

Required string length: 5 - 200
Example:

"Senior TypeScript Developer"

​
description
string

Job description

Required string length: 10 - 5000
Example:

"We are looking for an experienced TypeScript developer..."

​
jobUrl
string

Job URL

Example:

"https://company.com/careers/senior-typescript-dev"

​
benefits
string

Benefits

Example:

"Health insurance, remote work, flexible hours"

​
requiredSkills
string[]

Required skills

Maximum array length: 10
Example:
["TypeScript", "React", "Node.js"]
​
niceToHaveSkills
string[]

Nice-to-have skills

Maximum array length: 10
Example:
["Docker", "AWS", "GraphQL"]
​
languageRequirements
object[]

Language requirements with proficiency levels

Maximum array length: 5
Example:
[
  { "language": "EN", "proficiency": "B2" },
  { "language": "SK", "proficiency": "C1" }
]
​
education
enum<string>[]

Education requirements

Available options:
UNDEFINED,
PRIMARY_EDUCATION,
SECONDARY_SCHOOL_STUDENT,
SECONDARY_WITHOUT_DIPLOMA,
SECONDARY_WITH_DIPLOMA,
POST_SECONDARY_VOCATIONAL,
UNIVERSITY_STUDENT,
BACHELOR_LEVEL,
MASTER_LEVEL,
POSTGRADUATE
Example:
["BACHELOR_LEVEL", "MASTER_LEVEL"]
​
experience
enum<string>

Experience level required

Available options:
UNDEFINED,
NO_EXPERIENCE,
LESS_THAN_1_YEAR,
ONE_TO_3_YEARS,
THREE_TO_5_YEARS,
FIVE_TO_10_YEARS,
TEN_TO_15_YEARS,
MORE_THAN_15_YEARS
Example:

"FIVE_TO_10_YEARS"

​
contractType
enum<string>

Contract type

Available options:
UNDEFINED,
FULL_TIME,
PART_TIME,
FREELANCE_CONTRACT,
TRADE_LICENSE,
INTERNSHIP
Example:

"FULL_TIME"

​
status
enum<string>
default:OPEN

Job status

Available options:
UNDEFINED,
OPEN,
CLOSED
Example:

"OPEN"

​
location
object

Job location

​
salary
object

Salary range with comprehensive validation: min and max must be >= 0, min < max, currency and period are required if min or max is provided, at least one of min or max must be provided if any salary field is present

Example:
{
  "min": 50000,
  "max": 80000,
  "currency": "USD",
  "period": "YEARLY"
}
​
metadata
object

Custom metadata for extensibility (max 10KB, 5 levels deep, 50 keys)

Example:
{
  "externalJobId": "JOB-12345",
  "department": "Engineering",
  "hiringManager": "Jane Doe"
}

Response

201 - application/json
​
id
string
required

Job ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
companyId
string
required

Company ID

Example:

"987e6543-e21b-12d3-a456-426614174000"

​
title
string
required

Job title

Example:

"Senior TypeScript Developer"

​
status
enum<string>
required

Job status

Available options:
UNDEFINED,
OPEN,
CLOSED
Example:

"OPEN"

​
createdAt
string
required

Created timestamp

Example:

"2024-11-16T10:30:00Z"

​
updatedAt
string
required

Updated timestamp

Example:

"2024-11-16T10:30:00Z"

​
description
string | null

Job description

Example:

"We are looking for an experienced TypeScript developer..."

​
jobUrl
string

Job URL

Example:

"https://company.com/careers/senior-typescript-dev"

​
benefits
string

Benefits

Example:

"Health insurance, remote work, flexible hours"

​
requiredSkills
string[]

Required skills

Example:
["TypeScript", "React", "Node.js"]
​
niceToHaveSkills
string[]

Nice-to-have skills

Example:
["Docker", "AWS"]
​
languageRequirements
object[]

Language requirements with proficiency levels

Example:
[
  { "language": "EN", "proficiency": "B2" },
  { "language": "SK", "proficiency": "C1" }
]
​
education
string[]

Education requirements

Example:
["BACHELORS"]
​
experience
string

Experience level

Example:

"SENIOR"

​
contractType
string

Contract type

Example:

"FULL_TIME"

​
location
object

Location information

​
salary
object

Salary range

Example:
{
  "min": 50000,
  "max": 80000,
  "currency": "USD",
  "period": "YEARLY"
}
​
metadata
object

Custom metadata

Example:
{
  "externalJobId": "JOB-12345",
  "department": "Engineering"
}