get https://{subdomain}.workable.com/spi/v3/employees/
Returns all relevant information for a specific employee. Required scope: r_employees. Accessible with user access tokens and with account level tokens that provide member_id query param.
This particular endpoint uses
r_employeesscope, which can be enabled through the Integrations section found within the Settings menu. Account level tokens needmember_idto 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": "[email protected]",
"personal_email": [
{
"row_id": "2432e",
"is_primary": true,
"value": "[email protected]"
}
],
"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": "[email protected]",
"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": "[email protected]"
}
],
"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": "[email protected]"
}
]
| 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
}