🚧
This particular endpoint uses r_employees scope, which can be enabled through the Integrations section found within the Settings menu. Account level tokens need member_id to work.

Results

Calling the /employees/:id endpoint will return an instance of an employee. This structure provides a detailed overview of the employee's profile, covering various aspects of their professional details, personal details, and other related attributes. An example of the response follows:

{
    "id": "2fbc",
    "firstname": "Rex",
    "lastname": "Abernathy",
    "preferred_name": "Rex",
    "employee_number": "5",
    "status": "status_active",
    "country": {
        "display": "United Kingdom of Great Britain and Northern Ireland",
        "value": "GB"
    },
    "address": {
        "id": "EiVMb25kb24gUm9hZCwgSGlnaGZpZWxkLCBTaGVmZmllbGQsIFVLIi4qLAoUChIJIdmY0omCeUgRIY6G2ETqMl0SFAoSCaX6k4JignlIEeIrQ_I8jUrB",
        "city": "Sheffield",
        "bounds": {
            "northeast": "53.36983958029149,-1.474926019708498",
            "southwest": "53.36714161970849,-1.477623980291502"
        },
        "coords": "53.36849059999999, -1.476275",
        "status": "PARTIAL_SUCCESS",
        "country": "United Kingdom",
        "zip_code": "S2",
        "state_code": "England",
        "subregion": "England",
        "street_name": "London Road",
        "country_code": "GB",
        "street_number": "",
        "location_string": "London Road, Highfield, Sheffield, UK"
    },
    "gender": "gender_male",
    "birthdate": "1987-09-23T00:00:00.000Z",
    "marital_status_group": {
        "marital_status": "marital_status_married"
    },
    "phone_group": [
        {
            "row_id": "22b5e",
            "is_primary": true,
            "value": {
                "phone_type": "phone_type_mobile",
                "phone": "+18579909723"
            }
        }
    ],
    "work_email": "rex_abernathy@sampleemployee.com",
    "personal_email": [
        {
            "row_id": "2432e",
            "is_primary": true,
            "value": "rex_abernathy@gmail.com"
        }
    ],
    "chat_group": [
        {
            "row_id": "2431e",
            "is_primary": true,
            "value": {
                "chat_type": "chat_type_slack",
                "chat_username": "rex"
            }
        },
        {
            "row_id": "2431f",
            "is_primary": false,
            "value": {
                "chat_type": "chat_type_google_meet",
                "chat_username": "rex"
            }
        }
    ],
    "social_group": [
        {
            "row_id": "24320",
            "is_primary": true,
            "value": {
                "social_type": "social_type_facebook",
                "social_url": "https://facebook.com/im/rex"
            }
        }
    ],
    "job_title": "Account Manager ",
    "hire_date": "2021-10-01T00:00:00.000Z",
    "start_date": "2021-10-08T00:00:00.000Z",
    "legal_entity": "e697173f-5853-48c0-8eb4-b9c67ca11a93",
    "department": "3ff4d641",
    "reports_to": "2fce",
    "direct_reports": [],
    "employment_group": [
        {
            "row_id": "22b5f",
            "is_primary": true,
            "value": {
                "employment_effective_date": "2021-10-08T00:00:00.000Z",
                "employment_status": "employement_type_full_time"
            }
        }
    ],
    "work_schedule": "5c6",
    "salary_group": [
        {
            "row_id": "22b60",
            "is_primary": true,
            "value": {
                "salary_effective_date": "2021-10-08T00:00:00.000Z",
                "salary_pay_type": "salary_pay_type_salary",
                "salary_pay_rate": {
                    "amount": 90000,
                    "currency": "USD",
                    "frequency": "year"
                },
                "salary_pay_schedule": "salary_pay_schedule_every_15_days",
                "salary_overtime_status": "salary_overtime_status_exempt",
                "salary_justification": "salary_justification_new_hire"
            }
        }
    ],
    "bank_details_group": {
        "bank_details_bank_name": "Sterling",
        "bank_details_iban": "STR123456789",
        "bank_details_account_number": "234434"
    },
    "social_security_number_group": {
        "social_security_number_number": "XI5542",
        "social_security_number_issue_date": "1992-05-05T00:00:00.000Z"
    },
    "national_identification_number_group": {
        "national_identification_number_number": "XI5542",
        "national_identification_number_issue_date": "1992-05-05T00:00:00.000Z"
    },
    "social_insurance_number_group": [
        {
            "row_id": "24324",
            "is_primary": true,
            "value": {
                "social_insurance_number_number": "XI5543",
                "social_insurance_number_issue_date": "1992-05-05T00:00:00.000Z"
            }
        }
    ],
    "tax_identification_number_group": {
        "tax_identification_number_number": "IX444301",
        "tax_identification_number_issue_date": "1992-05-05T00:00:00.000Z"
    },
    "nationality": {
        "display": "United Kingdom of Great Britain and Northern Ireland",
        "value": "GB"
    },
    "citizenship": [
        {
            "row_id": "24327",
            "is_primary": true,
            "value": {
                "display": "United Kingdom of Great Britain and Northern Ireland",
                "value": "GB"
            }
        }
    ],
    "passport_group": [
        {
            "row_id": "24328",
            "is_primary": true,
            "value": {
                "passport_country": {
                    "display": "United Kingdom of Great Britain and Northern Ireland",
                    "value": "GB"
                },
                "passport_number": "XIPAS12345",
                "passport_issue_date": "2005-05-05T00:00:00.000Z",
                "passport_expiration_date": "2024-05-05T00:00:00.000Z"
            }
        }
    ],
    "visa_group": [],
    "education_group": [
        {
            "row_id": "24329",
            "is_primary": true,
            "value": {
                "education_start_date": "2004-09-01T00:00:00.000Z",
                "education_end_date": "2005-09-01T00:00:00.000Z",
                "education_degree": "MSc",
                "education_field_of_study": "Marketing",
                "education_school": "UMIST"
            }
        }
    ],
    "work_experience_group": [
        {
            "row_id": "2432a",
            "is_primary": true,
            "value": {
                "work_experience_start_date": "2008-05-01T00:00:00.000Z",
                "work_experience_end_date": "2019-05-01T00:00:00.000Z",
                "work_experience_job_title": "Marketing Associate",
                "work_experience_company": "Tesco"
            }
        }
    ],
    "skills": [
        {
            "row_id": "2432b",
            "is_primary": true,
            "value": "MS Office"
        }
    ],
    "language": [
        {
            "row_id": "2432c",
            "is_primary": true,
            "value": "Hebrew"
        }
    ],
    "contact_group": [
        {
            "row_id": "2432d",
            "is_primary": true,
            "value": {
                "contact_name": "Roxane Abernathy",
                "contact_relationship": "contact_relationship_type_mother",
                "contact_phone": "+1123456789",
                "contact_email": "roxane@gmail.com",
                "contact_country": {
                    "display": "United Kingdom of Great Britain and Northern Ireland",
                    "value": "GB"
                }
            }
        }
    ],
    "1195b": [
        {
            "row_id": "282b1",
            "is_primary": true,
            "value": {
                "1195c": "7f64",
                "1195d": "Custom contact field value 1"
            }
        }
    ]
}

📘
Permissions and available employee record values through API
Every employee is set up using a predefined template. This template has settings that determine who can see which fields. The API uses user tokens for authorization. Depending on the role associated with the token, some information might be hidden. For instance, an HR admin can view all the information, but regular members or managers might only see parts of it, based on the template's settings. Below, you'll find an example of how a specific field is configured.

The above example response is for a user token with HR admin permissions. Let's see what is the response for a simple member that is not a manager of the specific employee.

{
    "id": "2fbc",
    "firstname": "Rex",
    "lastname": "Abernathy",
    "preferred_name": "Rex",
    "employee_number": "5",
    "country": {
        "display": "United Kingdom of Great Britain and Northern Ireland",
        "value": "GB"
    },
    "birthdate": "1987-09-23T00:00:00.000Z",
    "phone_group": [
        {
            "row_id": "22b5e",
            "is_primary": true,
            "value": {
                "phone_type": "phone_type_mobile",
                "phone": "+18579909723"
            }
        }
    ],
    "personal_email": [
        {
            "row_id": "2432e",
            "is_primary": true,
            "value": "rex_abernathy@gmail.com"
        }
    ],
    "chat_group": [
        {
            "row_id": "2431e",
            "is_primary": true,
            "value": {
                "chat_type": "chat_type_slack",
                "chat_username": "rex"
            }
        },
        {
            "row_id": "2431f",
            "is_primary": false,
            "value": {
                "chat_type": "chat_type_google_meet",
                "chat_username": "rex"
            }
        }
    ],
    "social_group": [
        {
            "row_id": "24320",
            "is_primary": true,
            "value": {
                "social_type": "social_type_facebook",
                "social_url": "https://facebook.com/im/rex"
            }
        }
    ],
    "job_title": "Account Manager ",
    "start_date": "2021-10-08T00:00:00.000Z",
    "legal_entity": "e697173f-5853-48c0-8eb4-b9c67ca11a93",
    "department": "3ff4d641",
    "reports_to": "2fce",
    "direct_reports": []
}

The above response contains only information that is publicly available through the user interface like Job title, Firstname, Lastname etc. Fields like social_group, chat_group, phone_group, personal_email and birthdate have been configured as visible to simple members through the default or custom profile template configuration.

Each employee will have the following keys which are part of the default employee template:

key	type	description
id	`string`	Unique identifier for the employee. Note that this `id` should be used when updating an employee using the `PATCH` endpoint
firstname	`string`	First name of the employee
lastname	`string`	Last name of the employee
preferred_name	`string`	Preferred name of the employee
employee_number	`string`	Employee's unique identification number. There is support for auto-increment or custom
status		Current status of the employee. Example value indicates an active status. Other values are `status_inactive` and `status_draft`. `status_draft` is the default initial status when a new employee is created. Draft employees are not visible in the Company Directory or Org Chart by simple members. The user with `hr_admin` role should publish them to become visible and change the status to `status_active`. To start the onboarding process an employee should be `status_draft`. `status_inactive` is the status after the off-boarding process. The employee should have `status_inactive` in order to enable the permanent deletion of the employee record
address	`object`	Contains information related to the employee's address. More information can be found below
gender	`string`	Gender of the employee. Default available options are `gender_male`, `gender_female` and `gender_non-binary`
birthdate	`date`	Birthdate of the employee in ISO 8601 format
marital_status_group	`object`	The marital status of the employee. Contains the marital_status key where default available options are `marital_status_group_single`, `marital_status_group_married`, `marital_status_group_common_law` and `marital_status_group_domestic_partnership`
phone_group	`array[object]`	Contains information of all the different types an employee can have. Is a multi-value composite field. More information can be found below
work_email	`string`	Employee's work email address
personal_email	`array[object]`	List of personal email addresses associated with the employee. Is a multi-value composite field with default email types: `email_type_personal`,`email_type_work`, `email_type_other`
chat_group	`array[object]`	Contains information on chat app user names of the employee. Is a multi-value composite field. More information can be found below
social_group	`array[object]`	Contains information on the social urls of the employee. Is a multi-value, composite field with default social networks: `social_type_facebook`, `social_type_linkedin` and `social_type_twitter`
job_title	`string`	Job title of the employee
hire_date	`date`	Date related to the employee's hiring date in ISO 8601 format
start_date	`date`	Date related to the employee's start date in ISO 8601 format
legal_entity	`string`	Reference to the legal entity the employee belongs to. This value can be associated with /legal_entities
department	`string`	Reference to the department the employee works in. This value can be associated with /departments
reports_to	`string`	Reference to whom the employee reports to (e.g., their manager). This id can be used to retrieve the manager profile using /employees/:id
direct_reports	`array[object]`	List of individuals who report to this employee. For more information see below
work_schedule	`string`	Reference to the work schedule the employee belongs to. This value can be associated with /work_schedules. Employees without work schedule can not use the time off component
salary_group	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values.
bank_details_group	`object`	Single value composite field. See the above example for the specific keys and example values
social_security_number_group	`object`	Single value composite field. See the above example for the specific keys and example values
national_identification_number_group	`object`	Single value composite field. See the above example for the specific keys and example values
social_insurance_number_group	`aaray[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values
employment_group	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values
tax_identification_number_group	`object`	Single value composite field. See the above example for the specific keys and example values
citizenship	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values
passport_group	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values
visa_group	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values
education_group	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values
work_experience_group	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values
skills	`array[string]`	Multi value string field. See the above example for the specific keys and example values
language	`array[string]`	Multi value string field. See the above example for the specific keys and example values
contact_group	`array[object]`	Multi value composite field. Follows similar structure as phone_group. See the above example for the specific keys and example values

address

Here is an example address response snippet:

"address": {
  "id": "EiVMb25kb24gUm9hZCwgSGlnaGZpZWxkLCBTaGVmZmllbGQsIFVLIi4qLAoUChIJIdmY0omCeUgRIY6G2ETqMl0SFAoSCaX6k4JignlIEeIrQ_I8jUrB",
  "city": "Sheffield",
  "bounds": {
    "northeast": "53.36983958029149,-1.474926019708498",
    "southwest": "53.36714161970849,-1.477623980291502"
  },
  "coords": "53.36849059999999, -1.476275",
  "status": "PARTIAL_SUCCESS",
  "country": "United Kingdom",
  "zipCode": "S2",
  "stateCode": "England",
  "subregion": "England",
  "streetName": "London Road",
  "countryCode": "GB",
  "streetNumber": "",
  "locationString": "London Road, Highfield, Sheffield, UK"
}

The address value goes through Google Maps normalisation. For more information on the response refer to Google Maps Geocoding API doc

phone_group

Here is an example phone_group response snippet:

"phone_group": [
  {
    "row_id": "22b5e",
    "is_primary": true,
    "value": {
      "phone_type": "phone_type_mobile",
      "phone": "+18579909723"
    }
  }
]

key	type	description
row_id	`string`	Each multi-value field has this attribute, that indicates the row number of the array. This value should be used to update the value of the field.
is_primary	`boolean`	Indicates if this phone number is the primary contact
value.phone_type	`string`	Contains phone type. Default available phone types are: `phone_group_type_work`, `phone_group_type_mobile`, `phone_group_type_home` and `phone_group_type_other`
value.phone	`string`	Actual phone number

personal_email

Here is an example personal_email response snippet:

"personal_email": [
  {
    "row_id": "2432e",
    "is_primary": true,
    "value": "rex_abernathy@gmail.com"
  }
]

key	type	description
row_id	`string`	Each multi-value field has this attribute, that indicates the row number of the array. This value should be used to update the value of the field.
is_primary	`boolean`	Indicates if this personal email is the primary one
value	`string`	The value of the email

chat_group

"chat_group": [
  {
    "row_id": "2431e",
    "is_primary": true,
    "value": {
      "chat_type": "chat_type_slack",
      "chat_username": "rex"
    }
  },
  {
    "row_id": "2431f",
    "is_primary": false,
    "value": {
      "chat_type": "chat_type_google_meet",
      "chat_username": "rex"
    }
  }
]

key	type	description
row_id	`string`	Each multi-value field has this attribute, that indicates the row number of the array. This value should be used to update the value of the field.
is_primary	`boolean`	Indicates if this chat type is the primary contact for chat communication
value.chat_type	`string`	Contains chat type. Default available chat types are: `chat_type_skype`, `chat_type_zoom`, `chat_type_whatsapp`, `chat_type_messenger`, `chat_type_google_meet` and `chat_type_slack`
value.chat_username	`string`	Actual value of the chat username

direct_reports

Managers can have direct reports. Below is an example of the snippet of the response of a manager with 3 direct reports:

"direct_reports": [
  {
    "id": "2fcg",
    "name": "Abernathy, Rex",
    "job_title": "Account Manager ",
    "avatar": "https://officedroid-hris.s3.amazonaws.com/demo/avatars/men/2.jpeg",
    "state": "published"
  },
  {
    "id": "2bce",
    "name": "Rodriguez, Mia",
    "job_title": "Account Manager ",
    "avatar": "https://officedroid-hris.s3.amazonaws.com/demo/avatars/women/3.jpeg",
    "state": "published"
  },
  {
    "id": "2cce",
    "name": "Sipes, Marc",
    "job_title": "Account Manager ",
    "avatar": "https://officedroid-hris.s3.amazonaws.com/demo/avatars/men/1.jpeg",
    "state": "published"
  }
]

key	type	description
id	`string`	Unique identifier for the employee. Note that this `id` could be used when updating or getting an employee using the `PATCH` or `GET` endpoint
name	`string`	The fullname of the employee
job_title	`string`	The job title of the employee
avatar	`string`	URL of the avatar of the employee. TTL 1 hour
state	`string`	The state of the employee. The value here can be only `published`

Custom fields

The power of the employee profile template its fluidity. One can set up the profile with what ever field suits its business better. The manifestation of this fluidity is the support of custom fields. Below is the response for an employee that has a custom field named Custom Contact field:

"1195b": [
  {
    "row_id": "282b1",
    "is_primary": true,
    "value": {
      "1195c": "7f63",
      "1195d": "Custom contact field value"
    }
  }
]

The above field is a multi value composite field. The first field 1195c is a dropdown selection with value 7f63 and the second one 1195d is a short text field with value Custom contact field value. The above is described in the response of the employee_fields endpoint (snippet for the specific field follows):

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

200200

400400