Skip to main content

​
Create a job

Create a new job posting with the specified requirements, skills, and evaluation criteria.

​
Endpoint

POST /api/jobs

​
Authentication

This endpoint requires authentication. Include your authentication credentials in the request.

​
Request body

​
title
string
required
The job title for the position.
​
company_id
string
The ID of the company posting this job. Auto-assigned if not provided.
​
required_skills
array
required
List of skills that are required for this position. Each item should be a string representing a skill (e.g., “Python”, “React”, “PostgreSQL”).
​
preferred_skills
array
default:"[]"
List of skills that are preferred but not required. Each item should be a string.
​
min_experience
integer
default:"0"
Minimum years of experience required for this position.
​
openings
integer
default:"1"
Number of open positions for this job.
​
weight_skill
integer
default:"30"
Weight assigned to skill matching in candidate evaluation (0-100).
​
weight_github
integer
default:"25"
Weight assigned to GitHub profile evaluation (0-100).
​
weight_interview
integer
default:"25"
Weight assigned to interview performance (0-100).
​
weight_experience
integer
default:"10"
Weight assigned to years of experience (0-100).
​
weight_integrity
integer
default:"10"
Weight assigned to integrity checks (0-100).

​
Response

Returns the created job object with an auto-generated ID.
​
id
string
Unique identifier for the job (8-character UUID).
​
company_id
string
The ID of the company that posted this job.
​
title
string
The job title.
​
required_skills
array
List of required skills for this position.
​
preferred_skills
array
List of preferred skills for this position.
​
min_experience
integer
Minimum years of experience required.
​
openings
integer
Number of open positions.
​
weight_skill
integer
Weight for skill evaluation.
​
weight_github
integer
Weight for GitHub evaluation.
​
weight_interview
integer
Weight for interview evaluation.
​
weight_experience
integer
Weight for experience evaluation.
​
weight_integrity
integer
Weight for integrity evaluation.

​
Status codes

​
200
Success
Job created successfully.
​
400
Bad Request
Invalid request body or missing required fields.
​
401
Unauthorized
Authentication credentials are missing or invalid.
​
500
Internal Server Error
An error occurred while creating the job.

​
Example request

curl -X POST https://api.fairmatch.ai/api/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "company_id": "comp_123",
    "title": "Senior Full Stack Engineer",
    "required_skills": ["Python", "React", "PostgreSQL"],
    "preferred_skills": ["Docker", "AWS", "TypeScript"],
    "min_experience": 3,
    "openings": 5,
    "weight_skill": 30,
    "weight_github": 25,
    "weight_interview": 25,
    "weight_experience": 10,
    "weight_integrity": 10
  }'

​
Example response

{
  "id": "a1b2c3d4",
  "company_id": "comp_123",
  "title": "Senior Full Stack Engineer",
  "required_skills": ["Python", "React", "PostgreSQL"],
  "preferred_skills": ["Docker", "AWS", "TypeScript"],
  "min_experience": 3,
  "openings": 5,
  "weight_skill": 30,
  "weight_github": 25,
  "weight_interview": 25,
  "weight_experience": 10,
  "weight_integrity": 10
}

Build docs developers (and LLMs) love

Get started for freeTalk to us