Post a job

Requires a production key with the jobs:write scope. To upgrade from eval access, email hello@cutshort.io. For API support, email engineering@cutshort.io from your Cutshort account email.

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

{
  "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

{
  "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

Use Search candidates to validate role criteria and pool size
Post the job with aligned title, experience, salary, and locations
Invite shortlisted candidates to apply
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

Getting started

Guides

Request

Fields

`keyRequirements` rules

Response

Delete a job

Rate limit

Typical flow with search

Errors

​Request

​Fields

​keyRequirements rules

​Response

​Delete a job

​Rate limit

​Typical flow with search

​Errors

Request

Fields

`keyRequirements` rules

Response

Delete a job

Rate limit

Typical flow with search

Errors