Rolefy

API reference / Jobs

Create a job

POST/v1/jobs

Needs a bearer access token with the jobs.write scope. How authentication works

Creates a job for your employer. Pass your own id as external_job_id to be able to update it later by that id. To create or update in a single call, use PUT /v1/jobs/by-external-id/{externalJobId} instead. Pushing a job to Rolefy

Request bodyapplication/jsonrequired

  • titlestringrequired
  • descriptionstringrequired

    Plain text or simple HTML.

  • job_typestringnullable

    For example full_time, part_time, contract, casual.

  • work_modelstringnullable

    For example onsite, hybrid, remote.

  • experience_levelstringnullable
  • category_idstring · uuidnullable

    From /v1/job-categories.

  • citystringnullable
  • statestringnullable
  • countrystringrequired
  • salary_minnumbernullable
  • salary_maxnumbernullable
  • salary_currencystring

    Default AUD.

  • salary_periodstring

    Default annual.

  • statusstring

    Default active.

    Allowed values:draftactiveclosed

  • expires_atstring · datenullable

    Default 30 days from now.

  • questionnairearray of QuestionnaireQuestion

    Screening questions. Sent in full every time: the job's questions are replaced by this list. Once the job has applications they can only be re-sent unchanged.

    • question_textstring
    • question_typestring

      text is a free answer, radio picks one option, checkbox picks any number. radio and checkbox need at least two options.

      Allowed values:textradiocheckbox

    • optionsarray of stringnullable

      The choices, for radio and checkbox questions.

    • is_requiredboolean
  • document_requirementsarray of DocumentRequirement

    Documents candidates must or may upload. Sent in full every time, like the questionnaire.

    • document_namestring

      Your own label for the document. Rolefy creates a matching document type for the employer the first time it sees a new name.

    • requirementstring

      Allowed values:requiredoptional

  • external_job_idstring

    Your own id for this job. Must be unique among your jobs.

Responses

  • 201Job created
    Response fields
    • dataJob
      • idstring · uuid
      • external_job_idstringnullable

        Your own id for this job.

      • titlestring
      • descriptionstring
      • job_typestringnullable
      • work_modelstringnullable
      • experience_levelstringnullable
      • category_idstring · uuidnullable
      • citystringnullable
      • statestringnullable
      • countrystring
      • salary_minnumbernullable
      • salary_maxnumbernullable
      • salary_currencystring
      • salary_periodstring
      • statusstring

        You can set draft, active and closed. The others are set by Rolefy.

        Allowed values:draftpending_approvalactiveexpiredclosedrejectedtaken_down

      • expires_atstring · datenullable
      • applications_countinteger
      • public_urlstringnullable

        The job's page on Rolefy. Null for sandbox jobs.

      • created_atstring · date-time
      • updated_atstring · date-time
  • 400Invalid request (invalid_request)
    Example response
    {
  "error": {
    "code": "invalid_request",
    "message": "Invalid request (`invalid_request`)."
  }
}