Rolefy

API reference / Jobs

Create or update a job by your own id

PUT/v1/jobs/by-external-id/{externalJobId}

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

Creates the job if none exists yet for this externalJobId (same request body as POST /v1/jobs), or replaces the fields you send on the existing one. This is the call to use for a sync: send the job every time it changes, and re-sending the same job is always safe. Responds 201 when it created the job and 200 when it updated one.

Path parameters

  • externalJobIdstringpathrequired

    Your own id for this job.

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

Responses

  • 200Job updated
  • 201Job created
  • 400Invalid request (invalid_request)
    Example response
    {
  "error": {
    "code": "invalid_request",
    "message": "Invalid request (`invalid_request`)."
  }
}