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

# Jobs: AI-Powered Role Matching and Management in Cutshort

> Learn how Cutshort job objects work, what fields drive AI-powered candidate matching, and how to write descriptions that produce high-quality shortlists.

A job in Cutshort represents an open role at your organization. Jobs are the primary input to Cutshort's AI matching engine — the more detail you provide, the better the candidate shortlists you receive. You can create and manage jobs programmatically via the API.

## Job data model

Every job object returned by the API contains the following fields:

<ResponseField name="id" type="string" required>
  Unique identifier for the job.
</ResponseField>

<ResponseField name="title" type="string" required>
  Job title for the open role (e.g., `Senior Backend Engineer`).
</ResponseField>

<ResponseField name="description" type="string" required>
  Full job description. Markdown formatting is supported — use it to structure responsibilities, requirements, and company context clearly.
</ResponseField>

<ResponseField name="skills_required" type="array of strings" required>
  Technical skills that candidates must have for this role (e.g., `["Go", "Kubernetes", "PostgreSQL"]`).
</ResponseField>

<ResponseField name="skills_preferred" type="array of strings">
  Nice-to-have technical skills that are not strictly required but improve a candidate's fit score.
</ResponseField>

<ResponseField name="experience_min" type="integer" required>
  Minimum years of professional experience required for the role.
</ResponseField>

<ResponseField name="experience_max" type="integer">
  Maximum years of professional experience. Candidates above this ceiling are treated as overqualified and may be filtered from shortlists.
</ResponseField>

<ResponseField name="location" type="string">
  Job location. Pass a city name (e.g., `Bangalore`) or `Remote` for fully distributed roles.
</ResponseField>

<ResponseField name="remote_type" type="string">
  Work arrangement for the role. One of `onsite`, `remote`, or `hybrid`.
</ResponseField>

<ResponseField name="salary_min" type="integer">
  Minimum annual salary offered for this role, in INR.
</ResponseField>

<ResponseField name="salary_max" type="integer">
  Maximum annual salary offered for this role, in INR.
</ResponseField>

<ResponseField name="status" type="string">
  Current lifecycle state of the job. One of `active`, `paused`, or `closed`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp recording when the job was created (e.g., `2024-08-15T09:30:00Z`).
</ResponseField>

<ResponseField name="shortlist_count" type="integer">
  Number of candidates currently in the AI-generated shortlist for this job.
</ResponseField>

***

## How jobs power AI matching

Once you create a job, Cutshort's **Role Matcher** semantically maps it to the 4M+ candidate pool — no manual keyword searching required. The AI reads the full job description to extract and reason about:

* **Required tech stack** — specific languages, frameworks, databases, and cloud platforms
* **Seniority level** — inferred from experience range, title, and responsibilities
* **Company stage fit** — startup-ready vs. enterprise-scale engineering environments
* **Domain expertise** — product verticals like fintech, B2C, SaaS, and deep tech

Because the Role Matcher works semantically, two jobs with different wording but equivalent requirements will surface the same high-fit candidates. The richer your description, the more precisely the matcher can discriminate between strong and marginal candidates.

***

## Job statuses

| Status   | Behaviour                                                                                                                                                  |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active` | The job is live. Sourcing runs continuously and the role is visible to matching candidates.                                                                |
| `paused` | Sourcing is paused and the job is hidden from candidates. Existing shortlists are preserved. Use this when you need to temporarily stop inbound responses. |
| `closed` | The role has been filled or cancelled. No new applications are accepted and the job no longer appears in sourcing workflows.                               |

***

## Writing effective job descriptions

The quality of your shortlist is directly proportional to the quality of your job description. The Role Matcher has more signal to work with when your description is specific and structured.

<Tip>
  To get the highest-quality shortlists, make sure your job description includes:

  * **Specific tech stack requirements** — list languages, frameworks, and infrastructure tools explicitly rather than broad categories
  * **Product or domain context** — mention whether the product is B2C, fintech, developer tooling, etc., so the AI can match for domain experience
  * **Team size and engineering culture** — note whether candidates will join a 5-person startup or a 200-person platform team
  * **Remote and hybrid policy** — be explicit about expectations around location and in-office days

  Vague descriptions like "strong engineering background" produce broader, lower-precision shortlists. Specific descriptions produce tighter, higher-signal shortlists.
</Tip>