Skip to main content

Creating An Employee Job

In this short guide we will try to explain how to create an employee job.

Step 1: Covering the basics​

An employee job is describes the past, present and future employment contracts of an employee.

An employee job consists by default of a name, which is usually the job title, a start date and an end date. Additional employee job fields can be defined by the admin users in onboard. All employee jobs (in a business) share the same fields.

Step 2: Finding out the mandatory fields​

The list of employee job fields can be requested from the employee job fields API endpoint.

In this example we want to create an employee job for our "Product Manager" Maria Rossi (employee_id=abc123). With the following api call we can find out which employee job fields exists in our business.

GET https://your-business-subdomain.onboard.org/services/api/v1/employee_job_fields

The response of this call could for example look like this:

{
  "entries": [
    {
      "id": "RrB7LYD2",
      "type_of": "name",
      "accessor": "name",
      "name_de": "Bezeichnung",
      "name_it": "Mansione",
      "name_en": "Name",
      "hint_de": null,
      "hint_it": null,
      "hint_en": null,
      "placeholder_de": null,
      "placeholder_it": null,
      "placeholder_en": null,
      "values": null
    },
    {
      "id": "Gqzr56Z5",
      "type_of": "job_type",
      "accessor": "job_type",
      "name_de": "Vertragsart",
      "name_it": "Contratto",
      "name_en": "Contract type",
      "hint_de": null,
      "hint_it": null,
      "hint_en": null,
      "placeholder_de": null,
      "placeholder_it": null,
      "placeholder_en": null,
      "values": [
        {
          "id": "unknown",
          "label_de": "nicht definiert",
          "label_it": "non definito",
          "label_en": "not defined"
        },
        {
          "id": "unlimited",
          "label_de": "unbefristet",
          "label_it": "lavoro a tempo indeterminato",
          "label_en": "unlimited"
        },
        {
          "id": "limited",
          "label_de": "befristet",
          "label_it": "lavoro a tempo determinato",
          "label_en": "fixed-term"
        }
      ]
    },
    {
      "id": "KZBGJz4J",
      "type_of": "time_hours",
      "accessor": "time_hours",
      "name_de": "Arbeitsstunden",
      "name_it": "Ore di lavoro",
      "name_en": "Work Hours",
      "hint_de": null,
      "hint_it": null,
      "hint_en": null,
      "placeholder_de": null,
      "placeholder_it": null,
      "placeholder_en": null,
      "values": null
    }
  ]
}

Step 3: Creating an employee job​

To sum the previous step up, there are 3 custom employee job fields. The name (usually the job title), the contract type and the work hours. Additionaly we always have to provice a start date for every employee job, and because we know Maria Rossi will leave us at the end of the year 2024, we can also provide an end date.

To create the employee job, we make a post call to the endpoint POST /services/api/v1/employee_jobs with the following body:

{
  "employee_id": "abc123",
  "from": "2020-01-01",
  "to": "2024-12-31",
  "name": "Product Manager",
  job_type: "unlimited",
  time_hours: 40.0
}

The endpoint will create the employee job if all information has been provided correctly. Note that some fields, if not provided, will be set automatically. An example for this would be the job type, which will be set to unknown if no other job type is provided.

The success response should look like this:

{
  "id": "7bBJADz2",
  "employee_id": "abc123",
  "from": "2020-01-01",
  "to": "2024-12-31",
  "notes": null,
  "time_percentage": 60.0,
  "time_hours": 40.0,
  "job_type": "unlimited",
  "name": "Product Manager",
  "created_at": "2024-10-10T13:43:56.347Z",
  "updated_at": "2024-10-10T13:43:56.347Z"
}