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

# Post a job

> Create a job with auto-configured pipeline and outreach

<Note>
  Requires a **production key** with the `jobs:write` scope. To upgrade from eval access, email [hello@cutshort.io](mailto:hello@cutshort.io). For API support, email [engineering@cutshort.io](mailto:engineering@cutshort.io) from your Cutshort account email.
</Note>

`POST /jobs` creates a fully configured job from minimal input. Cutshort derives skills and tags, attaches an auto-generated screening questionnaire, and enables auto-outreach to matching candidates. After posting, the job is reviewed and then goes live — typically **\~30 minutes on business days**.

## Request

```json theme={null}
{
  "title": "Senior Data Engineer",
  "remoteType": "remote_okay",
  "locations": ["Bangalore", "Pune"],
  "experienceRange": { "min": 4, "max": 8 },
  "salaryRange": { "min": 2500000, "max": 4500000 },
  "hideSalary": false,
  "mandatorySkillsMatchType": "any",
  "roleType": "full_time",
  "jobDescription": "Full JD text…",
  "keyRequirements": [
    {
      "requirement": "Must have worked primarily on data engineering, not general backend",
      "importance": "must_have"
    },
    {
      "requirement": "Early-stage startup experience",
      "importance": "nice_to_have"
    }
  ]
}
```

### Fields

| Field                      | Required           | Notes                                                                                                                                                                                                       |
| -------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                    | Yes                | Max 80 characters                                                                                                                                                                                           |
| `remoteType`               | Yes                | `remote_only`, `remote_okay`, or `remote_not_okay`                                                                                                                                                          |
| `locations`                | If not remote-only | Plain city names — canonicalized server-side (max 5)                                                                                                                                                        |
| `experienceRange`          | Yes                | `{ min, max }` in years                                                                                                                                                                                     |
| `salaryRange`              | Yes                | INR per annum (`2500000` = ₹25 LPA)                                                                                                                                                                         |
| `hideSalary`               | No                 | `true` hides the salary range on the public job page (default `false`)                                                                                                                                      |
| `mandatorySkillsMatchType` | No                 | How derived must-have skills gate matching: `any` (match any) or `all` (match all). Defaults to `any` when omitted (same as the job-setup UI). Always persisted so the job can be edited later in Cutshort. |
| `roleType`                 | No                 | `full_time` (default) or `internship`                                                                                                                                                                       |
| `jobDescription`           | Yes                | Max 20,000 characters                                                                                                                                                                                       |
| `keyRequirements`          | No                 | Max 8 items                                                                                                                                                                                                 |
| `teamId`                   | No                 | Post under a specific team; defaults to your first team in the workspace                                                                                                                                    |

### `keyRequirements` rules

* Default importance is `nice_to_have`
* Use `must_have` only for outright-rejection criteria — we **strongly recommend at most 3** (more are accepted, but each must-have shrinks outreach reach)
* Over-tight must-haves shrink reach to zero — prefer `nice_to_have` for preferences

Experience range and (for non-remote roles) location criteria are added automatically — do not duplicate them in `keyRequirements`.

## Response

```json theme={null}
{
  "jobId": "…",
  "status": "submitted_for_review",
  "publicUrl": null
}
```

After posting, the job is **reviewed and then goes live**. Review typically takes **\~30 minutes on business days**. Matching-candidate outreach and the public job page start once approved; `publicUrl` populates when the job is live.

## Delete a job

```
DELETE /api/v1/jobs/{jobId}
```

Soft-deletes the job (same as deleting in the Cutshort UI). It disappears from `GET /jobs`. Optional body: `{ "reason": "duplicate_job", "reasonText": "…" }`.

## Rate limit

5 `createJob` + 120 global requests per 60 seconds per API key.

## Typical flow with search

1. Use [Search candidates](/guides/search-candidates) to validate role criteria and pool size
2. Post the job with aligned title, experience, salary, and locations
3. [Invite shortlisted candidates](/guides/invite-to-apply) to apply
4. Monitor applicants in the Cutshort product UI

## Errors

| `error_code`            | HTTP | Meaning                                             |
| ----------------------- | ---- | --------------------------------------------------- |
| `insufficient_scope`    | 403  | Key lacks `jobs:write` (eval keys cannot post jobs) |
| `location_not_resolved` | 400  | City name could not be canonicalized                |
| `no_team_in_workspace`  | 400  | Acting user has no team in workspace                |
| `team_not_in_workspace` | 400  | Provided `teamId` does not belong to your workspace |
| `job_create_failed`     | 502  | Upstream creation failed                            |