Skip to main content

Creating An Application

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

Step 1: Covering the basics​

An application is, as the name already indicates, a filled out form of an applicant and additional data which was retroactively added by recruiters.

In every business there is a default template for application forms, which determines which fields need to be provided for a generic application. While onboard theoretically supports job specific application forms, the are rarely ever used and the API endpoint only supports the default application fields.

Step 2: Finding out the mandatory fields​

The default template can be requested from the application fields API endpoint, by not passing any additional query parameters.

In this example we want to create an application for the "Product Manager" job opening (job_id=abc123). With the following api call we can find out which application fields exists for our business.

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

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

{
  "entries": [
    {
      "id": "A96ey16n",
      "type_of": "first_name",
      "accessor": "first_name",
      "required": true,
      "internal": 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,
      "internal": 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,
      "internal": 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
    },
    {
      "id": "Bqabi8FA",
      "type_of": "phone",
      "accessor": "phone",
      "required": false,
      "internal": false,
      "name_de": "Telefonnummer",
      "name_it": "Numero di telefono",
      "name_en": "Phone number",
      "hint_de": null,
      "hint_it": null,
      "hint_en": null,
      "placeholder_de": null,
      "placeholder_it": null,
      "placeholder_en": null,
      "values": null
    }
  ]
}

Step 3: Creating an application​

In the previous step we saw that the application form for the "Product Manager" job opening only has the four fiels first_name, last_name, gender, phone. Since the field phone number is not required, we will not provide it for our application, but we will provide the mandatory fields.

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

{
  "accept_terms_and_conditions": true,
  "job_id": "abc123",
  "first_name": "Maria",
  "last_name": "Rossi",
  "gender": "female"
}

The endpoint will create the application 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 application status, which will be set to unanswered if no other application_status_id is provided.

{
  "id": "A96ey16n",
  "job_id": "abc123",
  "accept_terms_and_conditions": true,
  "created_at": "2024-09-03T20:37:36.000Z",
  "updated_at": "2024-09-06T05:58:55.860Z",
  "application_status_id": "nyBnKYM3",
  "first_name": "Maria",
  "last_name": "Rossi",
  "gender": "female",
  "phone": null
}