Public API v1 — Job Roles
Public API v1 — Job Roles

Create a job role with a competency rubric

Create the role an interview is scored against. Omit competencies and BetterHire extracts 5–7 from the job description — the same extraction the dashboard runs. Supply them to use your own rubric.

The response says whether an AI-led interview can be scheduled on the role (interview_ready) and the shortest slot it fits, so a rubric that would be rejected at scheduling time is caught here.

title may be omitted: the extraction reads the title, level and company off the posting and returns them as inferred (validated; null when the text does not say). One role per title: a second role with the same title would make every role-by-title call on this API ambiguous, so that returns 409 with the existing role's id.

Rate limit: 50 requests/hour per API key. Supports Idempotency-Key.

post/api/public/v1/job-roles

Request

  • Base URL: https://api.thebetterhire.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.thebetterhire.ai/api/public/v1/job-roles
  • Auth: HTTP bearer

Request body

titlestring nullable

Omit to use the title read off the posting (inferred.title). 422 TITLE_REQUIRED when the text does not name the role either.

job_descriptionstring required

Full job description text. Competencies are extracted from it unless you supply them.

experience_levelstring nullable

entry, mid, senior, lead or executive. Sets the seniority the candidate is judged against and how deep the interview probes. Defaults to mid.

company_namestring nullable

Hiring company shown to candidates, when it is not your own organisation (agencies).

Example request

{
  "title": "Senior Backend Engineer",
  "competencies": [
    {
      "name": "Distributed systems design"
    }
  ],
  "experience_level": "senior"
}

Response

Successful Response

idstring required
titlestring required
experience_levelstring nullable
company_namestring nullable
created_atstring required
updated_atstring required

Example response

{
  "inferred": {
    "title": "Full-Stack Software Engineer"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.