/employees/:id

GET https://{subdomain}.workable.com/spi/v3/employees/{id}

Updates an existing employee. Required scope: w_employees.

🚧

This particular endpoint uses w_employees scope, which can be enabled through the Integrations section found within the Settings menu.

Body

An example body for updating the values for an already created employee follows:

JSON

{
    "employee": {
        "firstname": "Zinedina",
        "tax_identification_number_group": {
            "tax_identification_number_number": "IX444301",
            "tax_identification_number_issue_date": "1992-05-05T00:00:00.000Z",
            "tax_identification_number_file": {
                "url": "https://www.cheggindia.com/wp-content/uploads/2023/06/Tax-Identification-Number-India_-How-to-Apply-for-a-TIN-Online.png",
                "name": "tax_identification"
            }
        },
        "1195b": [
            {
                "value": {
                    "1195c": "7f63",
                    "1195d": "Manually created contact field value"
                }
            }
        ]
    }
}

The above example contains 3 different updates.

One for the firstname which is a simple text field that is straightforward.

The second is for a single-value composite field named tax_identification_number_group. It is important to note here that even if the tax_identification_number_number and tax_identification_number_issue_date where already set in the profile, we should send them again with the changed value which in this case is the tax_identification_number_file.

This example shows how one can upload a document sending it as an object with keys url a signed url that contains the file and name for the name of the file.

The third update refers to the custom field with id 1195b.

As we have seen in the /employee_fieldsresponse for the specific account, the structure for the custom field with id 1195b is the following:

JSON

{
  "id": "1195b",
  "account_id": "3da58cc2",
  "label": "Custom contact field",
  "hint": null,
  "type": "composite",
  "editable_by": "admin",
  "approvable_by": "admin",
  "viewable_by": "employee",
  "subfields": [
    {
      "id": "1195c",
      "account_id": "3da58cc2",
      "label": "Custom contact field dropdown",
      "hint": "Hint for custom contact field dropdown",
      "type": "dropdown",
      "position": 0,
      "choices": [
        {
          "id": "7f62",
          "employee_field_id": 70794,
          "account_id": "3da58cc2",
          "label": "Custom choice 1",
          "position": 0,
          "can_edit_mapping": true
        },
        {
          "id": "7f63",
          "employee_field_id": 70794,
          "account_id": "3da58cc2",
          "label": "Custom choice 2",
          "position": 1,
          "can_edit_mapping": true
        },
        {
          "id": "7f64",
          "employee_field_id": 70794,
          "account_id": "3da58cc2",
          "label": "Custom choice 3",
          "position": 2,
          "can_edit_mapping": true
        }
      ]
    },
    {
      "id": "1195d",
      "account_id": "3da58cc2",
      "label": "Custom contact field",
      "hint": "Hint for custom contact field",
      "type": "text",
      "position": 1
    }
  ],
  "keep_history": false,
  "is_multiple": true
}

This is a multi-value (is_multiple is true) composite field with id 1195b and it is comprised of two different subfields, the one with id: 1195c and the one with id: 1195d.

The first subfield is a drop down field, with 3 different values available (7f62, 7f63, 7f64). The second subfield is a text type field.

In the above example, the array denotes the multi value nature of the field. The subfield with id 1195c which is a dropdown field has the value 7f63 which is the second option. The value of subfield with id 1195d which is a text field has the value Manually created contact field value