> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cutshort.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and Manage Job Postings on Cutshort via the API

> Programmatically create job postings on Cutshort, manage their status lifecycle, and trigger AI candidate matching for each open role.

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.

<Steps>
  <Step title="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.

    <CodeGroup>
      ```bash curl theme={null}
      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
        }'
      ```

      ```python Python theme={null}
      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']}")
      ```
    </CodeGroup>
  </Step>

  <Step title="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.

    ```json theme={null}
    {
      "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](/guides/webhooks) to receive real-time notifications.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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"
      }'
    ```
  </Step>
</Steps>

## 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

<Tip>
  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".
</Tip>