Skip to main content

Creating An Employee

If you need help creating an employee, this is where you want to be. Follow the steps below to create an employee as intended by the creators.

For this guide we will create an onboard employee for our employee Maria Rossi.

Step 1: Covering the basics​

Before we create an employee we need to make sure we know what an employee is and what data is stored in an employee object. This can differ from client installation to client installation, so it's important that we know what data we need to provide.

There are specific fields that need to be provided for every employee, like the language, but most fields are fully customizable and will differ from business to business, like the employee name, gender, birthday ecc.

Step 2: Finding out the mandatory fields​

In every onboard installation there is a different list of employee fields. These can be customized by the user, but rarely do change after the initial setup.

GET https://your-business-subdomain.onboard.org/services/api/v1/employee_fields retrieves a list of employee fields. In our test environment only the fields first_name, last_name and gender are required, so we will only set those for the employee, but the core concept is the same for all fields.

We use the accessor of the field to set the field when we create the employee, so we need to remember to set first_name, last_name and gender. Note that these accessors aren't always readable and sometimes look like cf_{some_number}.

{
  "entries": [
    {
      "id": "A96ey16n",
      "type_of": "first_name",
      "accessor": "first_name",
      "required": true,
      "unique": false,
      "name_de": "Vorname",
      "name_it": "Nome",
      "name_en": "First name",
      "hint_de": null,
      "hint_it": null,
      "hint_en": null,
      "placeholder_de": null,
      "placeholder_it": null,
      "placeholder_en": null,
      "values": null
    },
    {
      "id": "94Y2D3zp",
      "type_of": "last_name",
      "accessor": "last_name",
      "required": true,
      "unique": false,
      "name_de": "Nachname",
      "name_it": "Cognome",
      "name_en": "Last name",
      "hint_de": null,
      "hint_it": null,
      "hint_en": null,
      "placeholder_de": null,
      "placeholder_it": null,
      "placeholder_en": null,
      "values": null
    },
    {
      "id": "Gqzrp3YZ",
      "type_of": "gender",
      "accessor": "gender",
      "required": true,
      "unique": false,
      "name_de": "Geschlecht",
      "name_it": "Genere",
      "name_en": "Gender",
      "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​

Now that we have prepared all the data we need to create an employee file for Maria, all we need to do is call the endpoint POST https://your-business-subdomain.onboard.org/services/api/v1/employee with the following body:

{
  "language": "it",
  "first_name": "Maria",
  "last_name": "Rossi",
  "gender": "female"
}

If we entered all the information correctly, the endpoint will return the created employee as follows:

{
  "id": "7bBJMyz2",
  "first_name": "Maria",
  "last_name": "Rossi",
  "created_at": "2024-01-01T11:53:55.662Z",
  "updated_at": "2024-01-01T11:53:55.662Z",
  "language": "it",
  "gender": "female",
  "employee_status_id": "q0Bp7zrE",
  "location_id": null,
  "department_id": null,
  ...
}

In addition to the fields we passed, the response will contain all unset fields with their initial and or null value. Note that the employee status id, if not passed in the body, will be automatically set to the id of the status with the type new.