Create and Manage Job Postings on Cutshort via the API

You can create, update, and close job postings entirely through the Cutshort API. Each job you create is automatically fed into Cutshort’s AI matching engine, which begins generating candidate shortlists based on the job’s requirements.

Create the job

Send a POST request to /v1/jobs with your job details. Include required skills, preferred skills, experience range, location, work model, and salary band to give the AI matching engine the richest possible signal.

curl -X POST 'https://api.cutshort.io/v1/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Senior Backend Engineer",
    "description": "We are hiring a Senior Backend Engineer to build scalable APIs for our B2C platform serving 10M users. You will work on Python/Django services, PostgreSQL, and AWS infrastructure.",
    "skills_required": ["Python", "Django", "PostgreSQL", "AWS"],
    "skills_preferred": ["Redis", "Celery", "Docker"],
    "experience_min": 4,
    "experience_max": 8,
    "location": "Bengaluru",
    "remote_type": "hybrid",
    "salary_min": 2000000,
    "salary_max": 3500000
  }'

import requests

job = {
    "title": "Senior Backend Engineer",
    "description": "We are hiring a Senior Backend Engineer to build scalable APIs for our B2C platform serving 10M users. You will work on Python/Django services, PostgreSQL, and AWS infrastructure.",
    "skills_required": ["Python", "Django", "PostgreSQL", "AWS"],
    "skills_preferred": ["Redis", "Celery", "Docker"],
    "experience_min": 4,
    "experience_max": 8,
    "location": "Bengaluru",
    "remote_type": "hybrid",
    "salary_min": 2000000,
    "salary_max": 3500000
}

response = requests.post(
    "https://api.cutshort.io/v1/jobs",
    json=job,
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
)
created = response.json()
print(f"Job created: {created['id']}")

Check the response

A successful 201 Created response returns the new job object. Save the id — you will use it to update the job, fetch shortlists, and correlate webhook events.

{
  "id": "job_4xRt2wPv",
  "title": "Senior Backend Engineer",
  "status": "active",
  "shortlist_count": 0,
  "created_at": "2024-01-15T09:00:00Z"
}

The shortlist_count starts at 0 and increases as Cutshort’s AI engine identifies matching candidates. Subscribe to the candidate.shortlisted webhook event to receive real-time notifications.

Update the job

Send a PATCH request to /v1/jobs/{job_id} to update any fields on an existing job. You can revise the salary range, adjust experience requirements, or pause the role.

curl -X PATCH 'https://api.cutshort.io/v1/jobs/job_4xRt2wPv' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "salary_max": 4000000,
    "status": "paused"
  }'

Only the fields you include in the request body are updated — all other fields remain unchanged.

Close the job

When a role is filled or cancelled, set status to "closed". Closing a job stops all new AI matching and outreach for that role. Existing shortlisted candidates remain visible in your dashboard for reference.

curl -X PATCH 'https://api.cutshort.io/v1/jobs/job_4xRt2wPv' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "closed"
  }'

Job status lifecycle

A job moves through the following statuses during its lifetime:

Status	Description
`active`	The job is live. AI matching and outreach are running.
`paused`	Matching and outreach are suspended. The job can be reactivated.
`closed`	The job is permanently closed. Matching and outreach stop completely.

The typical flow for a filled role is:

active → paused → active  (if hiring is temporarily on hold)
active → closed            (when the role is filled or cancelled)

You can move a job from paused back to active at any time by sending { "status": "active" } in a PATCH request.

Writing better job descriptions

Include the product domain, team size, and specific technical challenges in your description. AI matching improves significantly with richer descriptions — for example, mentioning “distributed systems at 10M users” attracts stronger candidates than generic language like “scalable backend work”.

Get Started

Core Concepts

Guides

MCP Server

Create and Manage Job Postings on Cutshort via the API

Job status lifecycle

Writing better job descriptions

​Job status lifecycle

​Writing better job descriptions

Job status lifecycle

Writing better job descriptions