--- updatedAt: 2026-05-05T09:50:12.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # Employee updated Triggered when an employee's field is updated. The payload includes only the fields that were explicitly changed. Calculated fields affected by an update (e.g., age when birthDate changes) are not included. This event is also sent when a table entry create or update causes employee-level fields to change; the payload then contains the affected field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this event when their entries change. In the right panel, open **Examples** and select **Payload Example** to see a real payload. # OpenAPI definition ```json { "openapi": "3.1.1", "info": { "title": "Employee data API", "description": "Access your employees data with the Public API", "license": { "name": "Proprietary", "url": "https://apidocs.hibob.com/docs/api-terms-of-use" }, "contact": { "name": "Hi Bob, Inc." }, "version": "1.0.0" }, "servers": [ { "url": "https://api.hibob.com/v1", "description": "Production" }, { "url": "https://api.sandbox.hibob.com/v1", "description": "Sandbox" } ], "x-readme": { "metrics-enabled": false }, "tags": [ { "name": "People", "description": "Operations for managing people and employee records" }, { "name": "Onboarding", "description": "Operations for onboarding wizards" }, { "name": "Metadata", "description": "Operations for company lists, fields, and metadata" }, { "name": "Employee Tables", "description": "Operations for employee tables (work, employment, lifecycle, salaries, equities, variable, training, bank accounts)" }, { "name": "Custom Tables", "description": "Operations for custom table metadata and entries" }, { "name": "Employee data Webhooks", "description": "Webhook events for employee and table entry operations" } ], "webhooks": { "employeeCreated": { "post": { "operationId": "post_webhook_employee-created", "tags": [ "Employee data Webhooks" ], "summary": "Employee created", "description": "Triggered when an employee is created.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeCreatedEvent" }, "example": { "companyId": 637323, "type": "employee.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeUpdated": { "post": { "operationId": "post_webhook_employee-updated", "tags": [ "Employee data Webhooks" ], "summary": "Employee updated", "description": "Triggered when an employee's field is updated.\n\nThe payload includes only the fields that were explicitly changed. Calculated\nfields affected by an update (e.g., age when birthDate changes) are not included.\n\nThis event is also sent when a table entry create or update causes employee-level fields to change; the payload then contains the affected field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this event when their entries change.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeUpdatedEvent" }, "examples": { "profileField": { "summary": "Profile field change", "value": { "companyId": 637323, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486", "fieldUpdates": [ { "id": "personal.birthDate" } ] } } }, "afterLifecycleTable": { "summary": "After lifecycle table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.893941", "version": "v2", "data": { "employeeId": "3332883854254932743", "fieldUpdates": [ { "id": "employee.recentLeaveStartDate" }, { "id": "internal.status" }, { "id": "employee.recentLeaveEndDate" }, { "id": "internal.lifecycleStatus" } ] } } }, "afterWorkTable": { "summary": "After work table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:28:55.545382", "version": "v2", "data": { "employeeId": "3332883904477528858", "fieldUpdates": [ { "id": "work.department" }, { "id": "work.title" }, { "id": "work.activeEffectiveDate" } ] } } }, "afterEmploymentTable": { "summary": "After employment table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:51:59.905057", "version": "v2", "data": { "employeeId": "3332883904477528858", "fieldUpdates": [ { "id": "payroll.employment.type" } ] } } }, "afterSalaryTable": { "summary": "After salary table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:17:21.974884", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "payroll.salary.activeEffectiveDate" }, { "id": "payroll.salary.payPeriod" }, { "id": "payroll.salary.monthlyPayment" }, { "id": "payroll.salary.yearlyPayment" }, { "id": "payroll.salary.payment" }, { "id": "payroll.salary.payFrequency" } ] } } }, "afterAddressTable": { "summary": "After address table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:19:35.027449", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "address.postCode" }, { "id": "address.country" } ] } } }, "afterVariablePayTable": { "summary": "After variable pay table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:16:38.725127", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "payroll.variable.Executive bonus.amount" }, { "id": "payroll.variable.Bonus.paymentPeriod" }, { "id": "payroll.variable.Bonus.amount" }, { "id": "payroll.variable.Bonus.payoutType" }, { "id": "payroll.variable.Executive bonus.payoutType" }, { "id": "payroll.variable.Executive bonus.paymentPeriod" } ] } } }, "afterEntitlementTable": { "summary": "After entitlement table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:15:08.446777", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "payroll.entitlement.Season ticket loans.amount" }, { "id": "payroll.entitlement.Childcare vouchers.amount" } ] } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeDeleted": { "post": { "operationId": "post_webhook_employee-deleted", "tags": [ "Employee data Webhooks" ], "summary": "Employee deleted", "description": "Triggered when an employee is deleted.\n\nThe payload includes the employee email so you can retain a reference to the\ndeleted employee after their record is no longer accessible.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDeletedEvent" }, "example": { "companyId": 639814, "type": "employee.deleted", "triggeredBy": "3647561042940134248", "triggeredAt": "2025-08-11T08:02:39.118536", "version": "v2", "data": { "employeeId": "3647561274138559361", "email": "zoe.clark_639814@samplebob.com" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeJoined": { "post": { "operationId": "post_webhook_employee-joined", "tags": [ "Employee data Webhooks" ], "summary": "Employee joined", "description": "Triggered when an employee is granted access, once the corresponding\nlifecycle entry becomes effective.\n\nLifecycle events are triggered automatically at midnight on the effective\ndate of the lifecycle table entry (according to the site's timezone).\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeJoinedEvent" }, "example": { "companyId": 637323, "type": "employee.joined", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeLeft": { "post": { "operationId": "post_webhook_employee-left", "tags": [ "Employee data Webhooks" ], "summary": "Employee terminated", "description": "Triggered when an employee is set as terminated or on Garden leave\n(whichever occurs first), once the corresponding lifecycle entry becomes effective.\n\nLifecycle events are triggered automatically at midnight on the effective\ndate of the lifecycle table entry (according to the site's timezone).\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeLeftEvent" }, "example": { "companyId": 637323, "type": "employee.left", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeActivated": { "post": { "operationId": "post_webhook_employee-activated", "tags": [ "Employee data Webhooks" ], "summary": "Employee activated", "description": "Triggered when an employee's access is enabled, once the corresponding\nlifecycle entry becomes effective.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeActivatedEvent" }, "example": { "companyId": 636192, "type": "employee.activated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.935613", "version": "v2", "data": { "employeeId": "3332883854254932743" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeInactivated": { "post": { "operationId": "post_webhook_employee-inactivated", "tags": [ "Employee data Webhooks" ], "summary": "Employee inactivated", "description": "Triggered when an employee is set to be on leave or terminated, once the\ncorresponding lifecycle entry becomes effective.\n\nThis event is not triggered if **Remain active** is selected when putting\nthe employee on leave.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeInactivatedEvent" }, "example": { "companyId": 636192, "type": "employee.inactivated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.915964", "version": "v2", "data": { "employeeId": "3332883854254932743" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeTemporaryLeave": { "post": { "operationId": "post_webhook_employee-temporary-leave", "tags": [ "Employee data Webhooks" ], "summary": "Employee on temporary leave", "description": "Triggered when an employee is set to be on temporary leave, once the\ncorresponding lifecycle entry becomes effective.\n\nThis event is not triggered if **Remain active** is selected when putting\nthe employee on leave.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeTemporaryLeaveEvent" }, "example": { "companyId": 636192, "type": "employee.temporaryLeave", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.935613", "version": "v2", "data": { "employeeId": "3332883854254932743" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "tableEntryCreated": { "post": { "operationId": "post_webhook_table-entry-created", "tags": [ "Employee data Webhooks" ], "summary": "Table entry created", "description": "Triggered when an entry is added to an employee's table (including\nout-of-the-box and custom tables).\n\nDoes not apply to Training, Equity, Positions, or Jobs tables.\n\nTo identify the row/entry when fetching using the API, use the property that appears in the payload for that table type:\n\n- **id** — Included only for non-historical tables (e.g. custom tables, bank accounts). Identifies the entry row. Omitted for historical tables.\n- **effectiveDate** — Included only for historical tables. Identifies the entry row for that table type. Omitted for non-historical tables.\n\nEach event includes exactly one of `effectiveDate` or `id` inside `data`, depending on whether the table is historical.\n\nTo learn more about table types, see Employee data modeling.\n\nWhen a table entry is created or updated, it may also update employee-level fields (e.g. derived or linked). In that case you will also receive an employee.updated event with the list of changed field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this additional employee.updated event.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } }, { "name": "get-table", "in": "header", "required": false, "description": "**Present only for custom tables.** The URL to call to read this table entry. For out-of-the-box tables the path is well known, but for custom tables this header provides the full URL with the table ID (e.g. `category_1716214820047__table_1716214839517`) already in the right place. Example: `https://api.hibob.com/v1/people/custom-tables/{employeeId}/{custom_table_id}`.", "schema": { "type": "string", "example": "https://api.hibob.com/v1/people/custom-tables/3332883884017713938/category_1716214820047__table_1716214839517" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableEntryCreatedEvent" }, "examples": { "lifecycle": { "summary": "Lifecycle", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.915906", "version": "v2", "data": { "employeeId": "3332883854254932743", "tableId": "lifecycle", "effectiveDate": "2025-01-08" } } }, "work": { "summary": "Work", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:28:55.561963", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "work", "effectiveDate": "2024-09-02" } } }, "employment": { "summary": "Employment", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:30:41.592528", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "employment", "effectiveDate": "2025-01-08" } } }, "bankAccounts": { "summary": "Bank accounts", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:54:03.608759", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "bankAccounts", "id": 6236350 } } }, "salary": { "summary": "Payroll (salary)", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:55:00.000000", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "salary", "effectiveDate": "2025-01-08" } } }, "customTable": { "summary": "Custom table", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:21:30.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "category_1716214820047__table_1716214839517", "id": 11542446 } } }, "address": { "summary": "Address", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:19:34.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "address", "effectiveDate": "2026-03-02" } } }, "variablePay": { "summary": "Variable Pay", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:16:37.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "variable", "effectiveDate": "2026-03-02" } } }, "entitlement": { "summary": "Entitlement", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:15:07.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "entitlement", "effectiveDate": "2026-03-03" } } }, "deduction": { "summary": "Deduction", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:13:18.445371", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "deduction", "effectiveDate": "2026-03-02" } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "tableEntryUpdated": { "post": { "operationId": "post_webhook_table-entry-updated", "tags": [ "Employee data Webhooks" ], "summary": "Table entry updated", "description": "Triggered when an entry is updated in an employee's table (including\nout-of-the-box and custom tables).\n\nDoes not apply to Training, Equity, Positions, or Jobs tables.\n\nTo identify the row/entry when fetching using the API, use the property that appears in the payload for that table type:\n\n- **id** — Included only for non-historical tables (e.g. custom tables, bank accounts). Identifies the entry row. Omitted for historical tables.\n- **effectiveDate** — Included only for historical tables. Identifies the entry row for that table type. Omitted for non-historical tables.\n\nEach event includes exactly one of `effectiveDate` or `id` inside `data`, depending on whether the table is historical.\n\nTo learn more about table types, see Employee data modeling.\n\nWhen a table entry is created or updated, it may also update employee-level fields (e.g. derived or linked). In that case you will also receive an employee.updated event with the list of changed field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this additional employee.updated event.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } }, { "name": "get-table", "in": "header", "required": false, "description": "**Present only for custom tables.** The URL to call to read this table entry. For out-of-the-box tables the path is well known, but for custom tables this header provides the full URL with the table ID (e.g. `category_1716214820047__table_1716214839517`) already in the right place. Example: `https://api.hibob.com/v1/people/custom-tables/{employeeId}/{custom_table_id}`.", "schema": { "type": "string", "example": "https://api.hibob.com/v1/people/custom-tables/3332883884017713938/category_1716214820047__table_1716214839517" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableEntryUpdatedEvent" }, "examples": { "lifecycle": { "summary": "Lifecycle", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:27.000000", "version": "v2", "data": { "employeeId": "3332883854254932743", "tableId": "lifecycle", "effectiveDate": "2025-01-08" } } }, "work": { "summary": "Work", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:28:05.816304", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "work", "effectiveDate": "2024-03-27" } } }, "employment": { "summary": "Employment", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:51:00.000000", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "employment", "effectiveDate": "2025-01-08" } } }, "salary": { "summary": "Payroll (salary)", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:55:45.055159", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "salary", "effectiveDate": "2015-03-03" } } }, "bankAccounts": { "summary": "Bank accounts", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:54:10.000000", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "bankAccounts", "id": 6236350 } } }, "customTable": { "summary": "Custom table", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:21:31.349254", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "category_1716214820047__table_1716214839517", "id": 11542446 } } }, "address": { "summary": "Address", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:19:35.027449", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "address", "effectiveDate": "2026-03-02" } } }, "variablePay": { "summary": "Variable Pay", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:16:38.749797", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "variable", "effectiveDate": "2026-03-02" } } }, "entitlement": { "summary": "Entitlement", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:15:08.471303", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "entitlement", "effectiveDate": "2026-03-03" } } }, "deduction": { "summary": "Deduction", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:13:20.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "deduction", "effectiveDate": "2026-03-02" } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } } }, "paths": { "/people/search": { "post": { "operationId": "post_people-search", "tags": [ "People" ], "summary": "Search for employees", "description": "Search employee fields for many employees in one call.

See Critical behaviors below on this page for field IDs, filters, showInactive, permissions, no pagination, large-company batching, and integration limits. Full contract: People read API contract.

Testing notes:

  1. Use Try It! and Examples > Request Example (default: active employees only; other examples cover terminated employees and batched reads by ID).
  2. Explore the response payload using the Example in the Response panel.
", "requestBody": { "description": "Select fields and options. See Critical behaviors below. Use Request Example for sample bodies (omit filters when not filtering).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadEmployeesRequestReference" }, "examples": { "defaultSearch": { "summary": "Default search (active employees only)", "description": "Default Try It example. See Critical behaviors below.", "value": { "fields": [ "root.id", "root.firstName" ], "showInactive": false, "filters": [ { "fieldPath": "root.id", "operator": "equals", "values": [ "3332883884017713938", "3332883909410030364" ] } ] } }, "discoverEmployeeIds": { "summary": "Discover employee IDs (lightweight)", "description": "ID discovery only. See Critical behaviors below.", "value": { "fields": [ "root.id" ], "showInactive": false } }, "includeTerminatedEmployees": { "summary": "Include terminated / inactive employees", "description": "showInactive true. See Critical behaviors below.", "value": { "showInactive": true, "fields": [ "root.id", "internal.status", "internal.lifecycleStatus" ] } }, "batchReadByEmployeeIds": { "summary": "Batch read by employee IDs", "description": "Batched root.id filter. See Critical behaviors below.", "value": { "fields": [ "root.id", "root.firstName", "work.department" ], "showInactive": false, "filters": [ { "fieldPath": "root.id", "operator": "equals", "values": [ "3332883884017713938", "3332883909410030364" ] } ] } } } } }, "required": true }, "responses": { "200": { "description": "Employees data response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employees" }, "examples": { "EmployeeResponseReadableExample": { "summary": "human readable only (humanReadable=\"REPLACE\")", "value": { "employees": [ { "fullName": "example", "displayName": "example", "creationDateTime": "2024-03-27T09:12:21.680867", "work": { "shortStartDate": "01/05", "startDate": "01/05/2015", "manager": "example", "tenureDuration": "9 years, 1 month and 26 days", "durationOfEmployment": "9 years, 1 month and 26 days", "reportsToIdInCompany": "30", "employeeIdInCompany": "40", "reportsTo": "example", "tenureDurationYears": "9.155", "department": "example", "siteId": "example", "tenureYears": "9", "isManager": "No", "title": "example", "site": "example", "originalStartDate": "01/05/2015", "activeEffectiveDate": "01/05/2015", "secondLevelManager": "example", "daysOfPreviousService": "0", "yearsOfService": "9.155" }, "avatarUrl": "string URL", "secondName": "example", "about": { "foodPreferences": "", "superpowers": "example", "hobbies": "example", "about": "string", "avatar": "string URL" }, "companyId": "636192", "email": "example@samplebob.com", "surname": "example", "coverImageUrl": "string URL", "id": "3332883884017713938", "firstName": "example" } ] } }, "EmployeeResponseMachineFormatExample": { "summary": "Machine format only (humanReadable=\"\")", "value": { "employees": [ { "fullName": "example", "/work/indirectReports": { "value": 33 }, "/about/avatar": { "string URL": null }, "/work/reportsTo/email": { "value": "example@samplebob.com" }, "displayName": "example", "/root/firstName": { "value": "example" }, "/work/employeeIdInCompany": { "value": 39 }, "/work/tenureDurationYears": { "value": 9.273 }, "/about/foodPreferences": { "value": [ "vegan" ] }, "/work/site": { "value": "New York (Demo)" }, "/work/tenureYears": { "value": 9 }, "creationDateTime": "2024-03-27T09:12:25.002884", "/about/hobbies": { "value": [ "yoga", "cooking", "261314348" ] }, "/root/email": { "value": "example@samplebob.com" }, "/work/title": { "value": "Desigexamplener" }, "employee": { "payrollManager": null, "hrbp": null, "itAdmin": null, "buddy": null }, "work": { "shortStartDate": "03-20", "startDate": "2015-03-20", "manager": "3332883909410030364", "tenureDuration": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" }, "custom": { "field_1711886937296": null }, "durationOfEmployment": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" }, "reportsToIdInCompany": 1, "employeeIdInCompany": 39, "reportsTo": { "displayName": "Zoe Clark", "email": "zoe.clark_636192@samplebob.com", "surname": "Clark", "firstName": "Zoe", "id": "3332883909410030364" }, "indirectReports": 33, "siteId": 2510068, "tenureDurationYears": 9.273, "department": "Product", "tenureYears": 9, "isManager": true, "title": "example", "site": "example", "originalStartDate": "2015-03-20", "activeEffectiveDate": "2015-03-20", "directReports": 1, "secondLevelManager": "3332883848206746373", "daysOfPreviousService": 0, "yearsOfService": 9.273 }, "/root/creationDateTime": { "value": "2024-03-27T09:12:25.002884" }, "secondName": null, "avatarUrl": "string URL", "/work/startDate": { "value": "2015-03-20" }, "about": { "foodPreferences": [ "vegan" ], "socialData": { "linkedin": null, "twitter": null, "facebook": null }, "superpowers": [ "excel" ], "hobbies": [ "yoga", "cooking", "261314348" ], "about": "string", "avatar": "string URL" }, "/root/fullName": { "value": "example" }, "companyId": 636192, "/root/coverImageUrl": { "value": "string URL" }, "/work/secondLevelManager": { "value": "3332883848206746373" }, "/work/directReports": { "value": 1 }, "/work/yearsOfService": { "value": 9.273 }, "/work/daysOfPreviousService": { "value": 0 }, "/about/about": { "value": "string" }, "/root/avatarUrl": { "value": "string URL" }, "/root/surname": { "value": "example" }, "/work/shortStartDate": { "value": "03-20" }, "/work/activeEffectiveDate": { "value": "2015-03-20" }, "/root/id": { "value": "3332883911884669725" }, "email": "amy.miles_636192@samplebob.com", "/work/manager": { "value": "3332883909410030364" }, "surname": "Miles", "/work/reportsTo": { "value": { "displayName": "Zoe Clark", "email": "zoe.clark_636192@samplebob.com", "surname": "Clark", "firstName": "Zoe", "id": "3332883909410030364" } }, "/root/companyId": { "value": 636192 }, "/root/displayName": { "value": "example" }, "/work/department": { "value": "example" }, "/work/isManager": { "value": true }, "/work/originalStartDate": { "value": "2015-03-20" }, "coverImageUrl": "string URL", "/work/reportsToIdInCompany": { "value": 1 }, "/work/tenureDuration": { "value": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" } }, "/about/superpowers": { "value": [ "excel" ] }, "id": "3332883911884669725", "firstName": "Amy", "/work/siteId": { "value": 2510068 }, "/work/durationOfEmployment": { "value": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" } } } ] } } } } } }, "400": { "description": "Bad request. The request contains incorrect parameters or syntax errors. Please review the request body" }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." }, "429": { "description": "\"Too Many Requests\" error. This indicates that you've exceeded the rate limit for requests. Please verify that you are using the correct endpoint with the POST method. Additionally, check the HTTP headers for rate limit information, such as the number of requests allowed and the time until the limit resets. For more details, see Rate Limiting." }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{identifier}": { "post": { "operationId": "post_people-identifier", "tags": [ "People" ], "summary": "Read company employee fields by employee ID.", "description": "Single-employee read endpoint (not bulk search): returns field data for one employee identified by backend ID or email in the path in a single response. No pagination. For many employees in one call, use Search for employees. See Pagination and result scope. This endpoint uses POST (not GET) because the request body selects fields.

Before using this endpoint — see the People read API contract and People API (rate limits, permissions table, troubleshooting):

Testing notes:

  1. Use the testing widget's Try It! option to test this endpoint.
  2. Use Examples > Request Example to see body parameters.
  3. Explore the response payload using the Example in the Response panel (human-readable and machine-format).
", "parameters": [ { "name": "identifier", "in": "path", "description": "The backend-id of the Employee. Retrieve this ID from the database.
For testing purposes, you can pull it from the URL in Bob when viewing the employee. For example, if the URL in Bob is \"https://app.hibob.com/employee-profile/3332883884017713238\" you should copy the \"3332883884017713238\".
Alternaticely you can provide the employee's email address.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Read request content that allows you to select fields and other options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadSingleEmployeeRequestReference" } } } }, "responses": { "200": { "description": "Employee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employees" }, "examples": { "EmployeeResponseReadableExample": { "summary": "Human readable format only (humanReadable=\"REPLACE\")", "value": { "employees": [ { "fullName": "example", "displayName": "example", "creationDateTime": "2024-03-27T09:12:21.680867", "work": { "shortStartDate": "01/05", "startDate": "01/05/2015", "manager": "example", "tenureDuration": "9 years, 1 month and 26 days", "durationOfEmployment": "9 years, 1 month and 26 days", "reportsToIdInCompany": "30", "employeeIdInCompany": "40", "reportsTo": "example", "tenureDurationYears": "9.155", "department": "Client Services", "siteId": "example", "tenureYears": "9", "isManager": "No", "title": "Account Manager", "site": "example", "originalStartDate": "01/05/2015", "activeEffectiveDate": "01/05/2015", "secondLevelManager": "v", "daysOfPreviousService": "0", "yearsOfService": "9.155" }, "avatarUrl": "string URL", "secondName": "example", "about": { "foodPreferences": "", "superpowers": "pitching,copywriting", "hobbies": "Rugby,Cycling,Running", "about": "string", "avatar": "string URL" }, "companyId": "636192", "email": "example@samplebob.com", "surname": "Tullin", "coverImageUrl": "string URL", "id": "3332883884017713938", "firstName": "example" } ] } }, "EmployeeResponseMachineFormatExample": { "summary": "Machine format only (humanReadable=\"\")", "value": { "employees": [ { "fullName": "v", "/work/indirectReports": { "value": 33 }, "/about/avatar": { "string URL": null }, "/work/reportsTo/email": { "value": "example@samplebob.com" }, "displayName": "example", "/root/firstName": { "value": "Amy" }, "/work/employeeIdInCompany": { "value": 39 }, "/work/tenureDurationYears": { "value": 9.273 }, "/about/foodPreferences": { "value": [ "vegan" ] }, "/work/site": { "value": "example" }, "/work/tenureYears": { "value": 9 }, "creationDateTime": "2024-03-27T09:12:25.002884", "/about/hobbies": { "value": [ "yoga", "cooking", "261314348" ] }, "/root/email": { "value": "example@samplebob.com" }, "/work/title": { "value": "Designer" }, "employee": { "payrollManager": null, "hrbp": null, "itAdmin": null, "buddy": null }, "work": { "shortStartDate": "03-20", "startDate": "2015-03-20", "manager": "3332883909410030364", "tenureDuration": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" }, "custom": { "field_1711886937296": null }, "durationOfEmployment": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" }, "reportsToIdInCompany": 1, "employeeIdInCompany": 39, "reportsTo": { "displayName": "v", "email": "example@samplebob.com", "surname": "example", "firstName": "example", "id": "3332883909410030364" }, "indirectReports": 33, "siteId": 2510068, "tenureDurationYears": 9.273, "department": "Product", "tenureYears": 9, "isManager": true, "title": "Designer", "site": "example", "originalStartDate": "2015-03-20", "activeEffectiveDate": "2015-03-20", "directReports": 1, "secondLevelManager": "3332883848206746373", "daysOfPreviousService": 0, "yearsOfService": 9.273 }, "/root/creationDateTime": { "value": "2024-03-27T09:12:25.002884" }, "secondName": null, "avatarUrl": "string URL", "/work/startDate": { "value": "2015-03-20" }, "about": { "foodPreferences": [ "vegan" ], "socialData": { "linkedin": null, "twitter": null, "facebook": null }, "superpowers": [ "excel" ], "hobbies": [ "yoga", "cooking", "261314348" ], "about": "string", "avatar": "string URL" }, "/root/fullName": { "value": "example" }, "companyId": 636192, "/root/coverImageUrl": { "value": "string URL" }, "/work/secondLevelManager": { "value": "3332883848206746373" }, "/work/directReports": { "value": 1 }, "/work/yearsOfService": { "value": 9.273 }, "/work/daysOfPreviousService": { "value": 0 }, "/about/about": { "value": "string" }, "/root/avatarUrl": { "value": "string URL" }, "/root/surname": { "value": "example" }, "/work/shortStartDate": { "value": "03-20" }, "/work/activeEffectiveDate": { "value": "2015-03-20" }, "/root/id": { "value": "3332883911884669725" }, "email": "amy.miles_636192@samplebob.com", "/work/manager": { "value": "3332883909410030364" }, "surname": "example", "/work/reportsTo": { "value": { "displayName": "Zoe Clark", "email": "zoe.clark_636192@samplebob.com", "surname": "Clark", "firstName": "Zoe", "id": "3332883909410030364" } }, "/root/companyId": { "value": 636192 }, "/root/displayName": { "value": "example" }, "/work/department": { "value": "Product" }, "/work/isManager": { "value": true }, "/work/originalStartDate": { "value": "2015-03-20" }, "coverImageUrl": "string URL", "/work/reportsToIdInCompany": { "value": 1 }, "/work/tenureDuration": { "value": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" } }, "/about/superpowers": { "value": [ "excel" ] }, "id": "3332883911884669725", "firstName": "example", "/work/siteId": { "value": 2510068 }, "/work/durationOfEmployment": { "value": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" } } } ] } } } } } }, "400": { "description": "Bad request. The request contains incorrect parameters or syntax errors. Please review the request body" }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." }, "429": { "description": "\"Too Many Requests\" error. This indicates that you've exceeded the rate limit for requests. Please verify that you are using the correct endpoint with the POST method. Additionally, check the HTTP headers for rate limit information, such as the number of requests allowed and the time until the limit resets. For more details, see Rate Limiting." }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "put": { "operationId": "put_people-identifier", "tags": [ "People" ], "summary": "Update company employee.", "description": "This endpoint allows you to update specific fields in an employee's record in Bob.

**Important**: Although this is a PUT method, it behaves like a PATCH request—you only need to send the fields you want to update, and any other fields will remain unchanged.

**Before using this endpoint**, read the instructions on how to update employee data. You can find them here: Update Employee data.

**Notes**:
  1. Only employee **fields** are supported; table updates are not allowed via this endpoint.
  2. **Position** fields cannot be updated using this endpoint.
  3. Recently updated employee data may take a few seconds to become available when fetching data. If you read immediately after an update, the response may still show the previous value or null. Wait up to 20 seconds before a follow-up read. See Read-after-update consistency.
", "parameters": [ { "name": "identifier", "in": "path", "description": "The backend-if of the Employee. Retrieve this ID from the database.
For testing purposes, you can pull it from the URL in Bob when viewing the employee. For example, if the URL in Bob is \"https://app.hibob.com/employee-profile/3332883884017713238\" you should copy the \"3332883884017713238\".", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Use Fields Metadata API for available field definitions.", "content": { "application/json": { "schema": { "description": "Specify the field IDs you want to update, and their values.
Ensure to specify the field ID in the correct format - you can copy the correct format from the result of the People Search endpoint. Please read the instructions here: Update Employee data.

**Important note**: We recommend testing this endpoint using an external tool, such as Postman, rather than the 'Try It!' feature in the documentation. This is because the parameters need to be constructed in a specific format. The easiest way to do this is by copying the parameter structure from the 'Search' endpoint's response.

For example:
{
\n \"home\": {
\n \"mobilePhone\": \"63635356\"
\n},

\n \"firstName\": \"Jacky\"
\n}", "type": "object", "example": { "firstName": "Bob", "personal": { "birthDate": "2002-01-01" }, "about": { "hobbies": [ "music", "travel", "sport" ] } } } } }, "required": true }, "responses": { "200": { "description": "Employee record was updated successfully.", "content": {} }, "304": { "description": "Returned when employee data has not been modified. Ensure that the data being sent is new and that the correct field ID and JSON structure are being used.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/profiles": { "get": { "operationId": "get_profiles", "tags": [ "People" ], "summary": "Read the public profile section of all active employees.", "description": "

Returns a predefined list of fields for all active employees the service user can access. Refer to the '200' response for the response schema.

Ensure the service user has the necessary permissions to access all the users and fields you want to retrieve, including the vasic default fields permissions.

Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

", "responses": { "200": { "description": "Employee profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeesProfiles" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people": { "post": { "operationId": "post_people", "tags": [ "People" ], "summary": "Create company employee.", "description": "
This endpoint allows you to create a new employee in the system.
The request body must include the minimum required fields: `email`, `firstName`, `surname`, and the `work` object with `site` and `startDate`.
While not all fields are mandatory, we recommend populating as many fields as possible to ensure complete employee records from the start.
Specifically, it's recommended to include `work.department` and `work.title`.
You can include **any additional fields** from the [Fields Metadata API](https://apidocs.hibob.com/reference/get_company-people-fields) to enrich the employee's profile during creation. ", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmployeeRequest" } } }, "required": true }, "responses": { "200": { "description": "Employee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeResponseMachineFormat" } } } }, "400": { "description": "Bad request. The request contains incorrect parameters or syntax errors. Please review the request body" }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." }, "429": { "description": "\"Too Many Requests\" error. This indicates that you've exceeded the rate limit for requests. Please verify that you are using the correct endpoint with the POST method. Additionally, check the HTTP headers for rate limit information, such as the number of requests allowed and the time until the limit resets. For more details, see Rate Limiting." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/employees/{identifier}/uninvite": { "post": { "operationId": "post_employees-identifier-uninvite", "tags": [ "People" ], "summary": "Revoke access to Bob for an employee.", "description": "

Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

", "parameters": [ { "name": "identifier", "in": "path", "description": "The backend-id of the Employee. Retrieve this ID from the database. For testing purposes, you can pull it from the URL in Bob when viewing the employee. For example, if the URL in Bob is \"https://app.hibob.com/employee-profile/3332883884017713238\" you should copy the \"3332883884017713238\".", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoke access successful.", "content": {} }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/employees/{identifier}/terminate": { "post": { "operationId": "post_employees-identifier-terminate", "tags": [ "People" ], "summary": "Terminate company employee.", "description": "This changes the employee’s status to Terminated according to specified termination date.

Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

", "parameters": [ { "name": "identifier", "in": "path", "description": "The backend-id of the Employee. Retrieve this ID from the database.
For testing purposes, you can pull it from the URL in Bob when viewing the employee. For example, if the URL in Bob is \"https://app.hibob.com/employee-profile/3332883884017713238\" you should copy the \"3332883884017713238\".", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeTermination" } } }, "required": true }, "responses": { "200": { "description": "Termination entry added successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/employees/{employeeId}/invitations": { "post": { "operationId": "post_employees-employeeid-invitations", "tags": [ "People" ], "summary": "Invite an employee with a welcome wizard ID.", "description": "

Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

", "parameters": [ { "name": "employeeId", "in": "path", "description": "The Employee ID as pulled from the database, or from the URL In Bob when viewing the employee.
For example, if the URL in Bob is \"https://app.hibob.com/employee-profile/3332883884017713238\" you should copy the \"3332883884017713238\".", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationByWizard" } } }, "required": true }, "responses": { "200": { "description": "Invitation submitted successfully.", "content": {} }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/employees/{employeeId}/start-date": { "post": { "operationId": "post_employees-employeeid-start-date", "tags": [ "People" ], "summary": "Set or update an employee's start date.", "description": "

Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

", "parameters": [ { "name": "employeeId", "in": "path", "description": "The backend-id of the Employee. Retrieve this ID from the database.
For testing purposes, you can pull it from the URL in Bob when viewing the employee. For example, if the URL in Bob is \"https://app.hibob.com/employee-profile/3332883884017713238\" you should copy the \"3332883884017713238\".", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartDateUpdate" } } }, "required": true }, "responses": { "200": { "description": "Start date was set successfully.", "content": {} }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/avatars": { "get": { "operationId": "get_avatars", "tags": [ "People" ], "summary": "Read avatar for an employee email", "description": "Returns the avatar image URL of the employee.", "parameters": [ { "name": "email", "in": "query", "description": "Employee email.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "URL of the employee avatar.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/avatars/{employeeId}": { "get": { "operationId": "get_avatars-employeeid", "tags": [ "People" ], "summary": "Read avatar for an employee ID.", "description": "Returns the avatar image URL of the employee.", "parameters": [ { "name": "employeeId", "in": "path", "description": "The Employee ID as pulled from the database, or from the URL In Bob when viewing the employee. For example, if the URL in Bob is \"https://app.hibob.com/employee-profile/3332883884017713238\" you should copy the \"3332883884017713238\".", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "URL of the employee avatar.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "put": { "operationId": "put_avatars-employeeid", "tags": [ "People" ], "summary": "Upload employee's avatar by image url", "description": "Upload an employee's Avatar by providing a URL to the image to upload.
", "parameters": [ { "name": "employeeId", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAvatar" } } }, "required": true }, "responses": { "200": { "description": "Avatar Uploaded successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/people/{id}/email": { "put": { "operationId": "put_people-id-email", "tags": [ "People" ], "summary": "Update an employee's email address.", "description": "Change an employee's email address. If you cannot change the self email an invitation will be sent to the new address to verify the email if the employee is invited/active.
", "parameters": [ { "name": "id", "in": "path", "description": "employee id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeEmail" } } }, "required": true }, "responses": { "200": { "description": "Invitation sent successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/onboarding/wizards": { "get": { "operationId": "get_onboarding-wizards", "tags": [ "Onboarding" ], "summary": "Get a summary of all onboarding wizards.", "description": "Wizard info includes Wizard ID, name and description.
Supported user types: Service.", "responses": { "200": { "description": "Onboarding Wizards", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingWizards" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/company/people/fields": { "get": { "operationId": "get_company-people-fields", "tags": [ "Metadata" ], "summary": "Get all employee fields.", "description": "This endpoint retrieves only metadata about the employee fields and includes all employee fields. Calling this endpoint does not require any permissions for the service user performing this action.

However, fetching the actual data requires setting the relevant permissions for the service user, including permissions to access employee data and relevant categories.
To learn more, see Search for employees .", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fields" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_company-people-fields", "tags": [ "Metadata" ], "summary": "Create a new field.", "requestBody": { "description": "The field to be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFieldRequest" } } }, "required": true }, "responses": { "200": { "description": "The new field was successfully created. The ID of the field is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldId" } } } }, "400": { "description": "If the category of the field is root, or historical is set to true, but the category doesn't allow it, or if the field type is not supported.", "content": {} }, "404": { "description": "If the category of the field doesn't exist", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/company/people/fields/{fieldId}": { "put": { "operationId": "put_company-people-fields-fieldid", "tags": [ "Metadata" ], "summary": "Update an existing field", "parameters": [ { "name": "fieldId", "in": "path", "description": "The ID of the field.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The new name and/or description of the updated field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFieldRequest" } } }, "required": true }, "responses": { "200": { "description": "The field was updated successfully.", "content": {} }, "404": { "description": "If the field doesn't exist.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" }, "delete": { "operationId": "delete_company-people-fields-fieldid", "tags": [ "Metadata" ], "summary": "Delete an existing field.", "parameters": [ { "name": "fieldId", "in": "path", "description": "The ID of the field.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The field was deleted successfully.", "content": {} }, "400": { "description": "If the field is a Bob default field.", "content": {} }, "404": { "description": "If the field doesn't exist", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/company/named-lists": { "get": { "operationId": "get_company-named-lists", "tags": [ "Metadata" ], "summary": "Get all company lists", "parameters": [ { "name": "includeArchived", "in": "query", "description": "By default (false), archived items are excluded from the response. When set to true, archived items are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lists" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/company/named-lists/{listName}": { "get": { "operationId": "get_company-named-lists-listname", "tags": [ "Metadata" ], "summary": "Get a specific company list by name.", "parameters": [ { "name": "listName", "in": "path", "description": "The internal name of the list.", "required": true, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived items are excluded from the response. When set to true, archived items are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response. Please note that the item ID may be textual or numeric depending on the list type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } }, "404": { "description": "If the list was not found.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_company-named-lists-listname", "tags": [ "Metadata" ], "summary": "Add a new item to an existing list.", "parameters": [ { "name": "listName", "in": "path", "description": "The internal name of the list.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The parentId attribute is optional and only applies to hierarchy lists. When parentId is specified, the newly created list item will be placed under the specific hierarchy parent node.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewListItem" } } }, "required": true }, "responses": { "200": { "description": "A new item is created. Please note that the ID of the newly created item may be textual or numeric depending on the list type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlatListItemId" } } } }, "404": { "description": "If the list was not found.", "content": {} }, "409": { "description": "If the added item already exists", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" } }, "/company/named-lists/{listName}/{itemId}": { "put": { "operationId": "put_company-named-lists-listname-itemid", "tags": [ "Metadata" ], "summary": "Update an existing item from a list.", "parameters": [ { "name": "listName", "in": "path", "description": "The internal name of the list.", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "The ID of the list item.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "You need to provide at least one of: name or parentId. Providing a name will rename the list item value. Providing the parent ID will move the hierarchy list item (together with its children) under the indicated parent node.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListItemRequest" } } }, "required": true }, "responses": { "200": { "description": "List item was updated successfully.", "content": {} }, "404": { "description": "If the list or item was not found.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" }, "delete": { "operationId": "delete_company-named-lists-listname-itemid", "tags": [ "Metadata" ], "summary": "Delete an item from an existing list.", "parameters": [ { "name": "listName", "in": "path", "description": "The internal name of the list.", "required": true, "schema": { "type": "string" } }, { "name": "itemId", "in": "path", "description": "The ID of the list item.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The list item was deleted successfully.", "content": {} }, "404": { "description": "If the list or item was not found", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/bulk/people/work": { "get": { "operationId": "get_bulk-people-work", "tags": [ "Employee Tables" ], "summary": "List work history for a list of employees", "description": "Returns a list of historical work entries from the work table for all employees or a specific list of employees.

**Required permissions**
In order to access the work history of each requested employee, the service user making the call must have the following permissions:
**For all the work table entries**: People's Data > Work > View selected employees' Work section histories.
**For the current effective work entry only**: People's Data > Work > View selected employees' Work sections.
**For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

\n**Pagination**
This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the number of table entries to include on each page of the results.", "required": false, "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "description": "A marker representing the first item on the next page to read. Make sure to URL encode this value before you send it as a query parameter. To learn more, see Pagination in Bob's API.", "required": false, "schema": { "type": "string" } }, { "name": "employeeIds", "in": "query", "description": "Comma separated list of employee ids. Maximum employees per request: 200. If this parameter is not passed, the API will return table entries for all the employees for which the service user has the permission for.", "required": false, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Work table entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWorkTableResponse" } } } }, "400": { "description": "Bad request." }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/bulk/people/lifecycle": { "get": { "operationId": "get_bulk-people-lifecycle", "tags": [ "Employee Tables" ], "summary": "List the lifecycle history for a list of employees.", "description": "Returns a list of historical lifecycle entries from the lifecycle table for all employees or a specific list of employees.

**Required permissions**
In order to access the lifecycle history of each requested employee, the service user making the call must have the following permissions:
**For all the lifecycle table entries**: People's Data > Lifecycle > View selected employees' Lifecycle section histories.
**For the current effective lifecycle entry only**: People's Data > Lifecycle > View selected employees' Lifecycle sections.
**For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.
\n\n**Pagination**
This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the number of table entries to include on each page of the results.", "required": false, "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "description": "A marker representing the first item on the next page to read. Make sure to URL encode this value before you send it as a query parameter. To learn more, see Pagination in Bob's API.", "required": false, "schema": { "type": "string" } }, { "name": "employeeIds", "in": "query", "description": "Comma separated list of employee ids. Maximum employees per request: 200. If this parameter is not passed, the API will return history records for all the employees for which the service user has the permission for.", "required": false, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Lifecycle table entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLifecycleTableResponse" } } } }, "400": { "description": "Bad request." }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/bulk/people/employment": { "get": { "operationId": "get_bulk-people-employment", "tags": [ "Employee Tables" ], "summary": "List employment history for a list of employees.", "description": "

Returns a list of historical employment entries from the employment table for all employees or a specific list of employees.

Each employment entry includes the working pattern assigned to this employee. To learn more about working patterns, see How to work with Working patterns.

Required permissions

In order to access the employment history of each requested employee, the service user making the call must have the following permissions:

  • For all the employment table entries: People's Data > Employment > View selected employees' Employment section histories.

  • For the current effective employment entry only: People's Data > Employment > View selected employees' Employment sections.
  • For the employees: People's Data > Access data for: Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

    • Pagination

    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API.

    ", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the number of table entries to include on each page of the results.", "required": false, "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "description": "A marker representing the first item on the next page to read. Make sure to URL encode this value before you send it as a query parameter. To learn more, see Pagination in Bob's API.", "required": false, "schema": { "type": "string" } }, { "name": "employeeIds", "in": "query", "description": "Comma separated list of employee ids. Maximum employees per request: 200. If this parameter is not passed, the API will return history records for all the employees for which the service user has the permission for.", "required": false, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Employment table entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEmploymentTableResponse" } } } }, "400": { "description": "Bad request." }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/bulk/people/salaries": { "get": { "operationId": "get_bulk-people-salaries", "tags": [ "Employee Tables" ], "summary": "List payroll history (salaries) for a list of employees.", "description": "Returns a list of historical salary entries from the payroll table for all employees or a specific list of employees.

    **Required permissions**
    In order to access the payroll history of each requested employee, the service user making the call must have the following permissions:
    **For all the salary table entries**: People's Data > Payroll > View selected employees' Payroll section histories.
    **For the current effective salary entry only**: People's Data > Payroll > View selected employees' Payroll sections.
    **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.
    \n\n**Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the number of table entries to include on each page of the results.", "required": false, "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "description": "A marker representing the first item on the next page to read. Make sure to URL encode this value before you send it as a query parameter. To learn more, see Pagination in Bob's API.", "required": false, "schema": { "type": "string" } }, { "name": "employeeIds", "in": "query", "description": "Comma separated list of employee ids. Maximum employees per request: 200. If this parameter is not passed, the API will return history records for all the employees for which the service user has the permission for.", "required": false, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Payroll (salaries) table entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSalariesTableResponse" } } } }, "400": { "description": "Bad request." }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/bulk/people/dependents": { "get": { "operationId": "get_bulk-people-dependents", "tags": [ "Employee Tables" ], "summary": "List dependents for a list of employees", "description": "Returns dependent entries for all employees or a specific list of employees. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > Home > View selected employees' Home sections (or Manage), or the equivalent Children/Dependents table permissions when field-level permissions are enabled.
    **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

    \n**Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the number of table entries to include on each page of the results.", "required": false, "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "description": "A marker representing the first item on the next page to read. Make sure to URL encode this value before you send it as a query parameter. To learn more, see Pagination in Bob's API.", "required": false, "schema": { "type": "string" } }, { "name": "employeeIds", "in": "query", "description": "Comma separated list of employee ids. Maximum employees per request: 200. If this parameter is not passed, the API will return table entries for all the employees for which the service user has the permission for. You can fetch employee IDs using the People search endpoint.", "required": false, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Dependents table entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDependentsTableResponse" } } } }, "400": { "description": "Bad request." }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-internal": false } }, "/bulk/people/right-to-work": { "get": { "operationId": "get_bulk-people-right-to-work", "tags": [ "Employee Tables" ], "summary": "List right to work entries for a list of employees", "description": "Returns right to work entries for all employees or a specific list of employees.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > Right to Work > View selected employees' Right to Work sections (or the equivalent Right to Work table permissions when field-level permissions are enabled).
    **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

    \n**Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the number of table entries to include on each page of the results.", "required": false, "schema": { "type": "number", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "description": "A marker representing the first item on the next page to read. Make sure to URL encode this value before you send it as a query parameter. To learn more, see Pagination in Bob's API.", "required": false, "schema": { "type": "string" } }, { "name": "employeeIds", "in": "query", "description": "Comma separated list of employee ids. Maximum employees per request: 200. If this parameter is not passed, the API will return table entries for all the employees for which the service user has the permission for. You can fetch employee IDs using the People search endpoint.", "required": false, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Right to work table entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRightToWorkTableResponse" } } } }, "400": { "description": "Bad request." }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-internal": false } }, "/people/actual-payments/search": { "post": { "operationId": "post_people-actual-payments-search", "tags": [ "Employee Tables" ], "summary": "Search for actual payments", "description": "This endpoint allows you to search for actual payments based on various filters.

    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API

    Required permissions
    **For all the actual payments table entries**: People's Data > Payroll > View selected employees' Payroll section histories.
    **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

    **Testing notes**:
    1. Use the testing widget's **Try It!** option to test this endpoint.
    2. Request Example: Use the **Examples > Request example** option to see how to initiate body parameters.
    3. **To test more than a single filter**, copy the example to an external API testing app like Postman for better filtering options.
    4. Response Example: View the response payload using the **Response > Response example** option in the response on the right.", "requestBody": { "description": "The request body must include a filter by employee ID. ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActualPaymentsSearchRequest" } } } }, "responses": { "200": { "description": "Search results for actual payments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActualPaymentsSearchResponse" } } } }, "400": { "description": "Bad request." }, "401": { "description": "Missing authentication credentials." }, "403": { "description": "Forbidden. The service user does not have the required permissions." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/work": { "get": { "operationId": "get_people-id-work", "tags": [ "Employee Tables" ], "summary": "List employee's work history", "description": "Returns a list of historical work entries from the work table for an employee.

    **Required permissions**
    In order to access the work history, the service user making the call must have the following permissions:
    **For all the work table entries**: People's Data > Work > View selected employees' Work section histories.
    **For the current effective work entry only**: People's Data > Work > View selected employees' Work sections.
    **For the employee**: People's Data > Access data for > Make sure the employee is in the list.

    ", "parameters": [ { "name": "id", "in": "path", "description": "Employee backend-id.", "required": true, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of work history entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkEntries" } } } }, "400": { "description": "Bad request, see error description.", "content": {} }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employee. Check the permissions as explained in the endpoint description.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-id-work", "tags": [ "Employee Tables" ], "summary": "Create a new work entry for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Work entry to add. This must not conflict with another entry on the same effective date and site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry created successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" } }, "/people/{id}/work/{entry_id}": { "put": { "operationId": "put_people-id-work-entry-id", "tags": [ "Employee Tables" ], "summary": "Update a work entry in the employee's work history table.", "description": "This endpoint updates an entry in the employee’s work history table.
    The unique identifier for the work entry is the site and effective date.

    Note that the entire work entry will be overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values).

    Patch Update Flag:
    As a best practice, we recommend reading the entire work entry data, updating the necessary fields, and then writing back the entire entry. However, for legacy purposes, we provide the flag: patchUpdate=true, which functions similarly to a PATCH request.
    When using this flag, please note:
    1. Only the fields included in the payload will be updated; all others will remain unchanged.
    2. The identifier for the work entry should be entry_id, not the site/effective date.
    3. Note that using the patchUpdate approach is not recommended and should be reserved for legacy implementations only.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the employee you are updating. This can be the Employee ID from the URL in the user interface or the id field returned when retrieving an employee's data.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The ID of the entry in the work table which you are updating. To obtain the work entry use the GET /people/{id}/work endpoint.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry updated successfully.", "content": {} }, "404": { "description": "Requested entry not found. Nothing was changed", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" }, "delete": { "operationId": "delete_people-id-work-entry-id", "tags": [ "Employee Tables" ], "summary": "Deletes a work entry from a given employee's work history.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry deleted successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/employment": { "get": { "operationId": "get_people-id-employment", "tags": [ "Employee Tables" ], "summary": "List employee's employment history.", "description": "

    Returns a list of employment history entries for a given employee.

    Each employment entry includes the working pattern assigned to this employee. To learn more about working patterns, see How to work with Working patterns.

    Required permissions

  • For all the employment table entries: People's Data > Employment > View selected employees' Employment section histories.

  • For the current effective employment entry only: People's Data > Employment > View selected employees' Employment sections.
  • For the employees: People's Data > Access data for: Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

    • ", "parameters": [ { "name": "id", "in": "path", "description": "employee id", "required": true, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of employment history entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentEntries" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-id-employment", "tags": [ "Employee Tables" ], "summary": "Creates a new employment entry for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "employee id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Employment entry to add. This must not conflict with another entry on the same effective date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry created successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" } }, "/people/{id}/employment/{entry_id}": { "put": { "operationId": "put_people-id-employment-entry-id", "tags": [ "Employee Tables" ], "summary": "Update an employment entry from a given employee's employment history.", "description": "This endpoint updates an entry in the employee’s employment history table.

    Note that the entire employnebt entry will be overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values).

    ", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to update.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry updated successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" }, "delete": { "operationId": "delete_people-id-employment-entry-id", "tags": [ "Employee Tables" ], "summary": "Deletes an employment entry from a given employee's employment history.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to delete.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry deleted successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/lifecycle": { "get": { "operationId": "get_people-id-lifecycle", "tags": [ "Employee Tables" ], "summary": "List employee's lifecycle status history.", "description": "Returns a list of historical lifecycle entries from the lifecycle table for an employee.

    **Required permissions**
    In order to access the lifecycle history, the service user making the call must have the following permissions:
    **For all the lifecycle table entries**: People's Data > Lifecycle > View selected employees' Lifecycle section histories.
    **For the current effective lifecycle entry only**: People's Data > Lifecycle > View selected employees' Lifecycle sections.
    **For the employees**: People's Data > Access data for > Make sure the employee is in the list. ", "parameters": [ { "name": "id", "in": "path", "description": "Employee backend-id.", "required": true, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of life-cycle history entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LifeCycleEntries" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/salaries": { "get": { "operationId": "get_people-id-salaries", "tags": [ "Employee Tables" ], "summary": "List employee's salary history.", "description": "Returns a list of historical salary entries from the salary table in the payroll section for an employee.

    **Required permissions**
    In order to access the payroll history, the service user making the call must have the following permissions:
    **For all the salary table entries**: People's Data > Payroll > View selected employees' Payroll section histories.
    **For the current effective salary entry only**: People's Data > Payroll > View selected employees' Payroll sections.
    **For the employee**: People's Data > Access data for > Make sure the employee is in the list.", "parameters": [ { "name": "id", "in": "path", "description": "Employee backend-id.", "required": true, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of salary entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryEntries" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-id-salaries", "tags": [ "Employee Tables" ], "summary": "Creates a new salary entry for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee backend-id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Salary entry to add. This must not conflict with another entry on the same effective date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalaryEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry added successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" } }, "/people/{id}/salaries/{entry_id}": { "delete": { "operationId": "delete_people-id-salaries-entry-id", "tags": [ "Employee Tables" ], "summary": "Deletes a salary entry from the employee's list.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to delete.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry deleted successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/payroll/history": { "get": { "operationId": "get_payroll-history", "tags": [ "Employee Tables" ], "summary": "Read payroll tables history.", "description": "Note: This endpoint is maintained for legacy purposes but is planned for deprecation in the future. We recommend using alternative employee table endpoints where possible.", "parameters": [ { "name": "department", "in": "query", "description": "filter payroll for specific department.", "schema": { "type": "string" } }, { "name": "showInactive", "in": "query", "description": "When `true`, includes inactive (typically terminated) employees in payroll history results. Default is active employees only. For employee field search, use `showInactive` on `POST /people/search` instead.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Payroll data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeesPayrollData" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/equities": { "get": { "operationId": "get_people-id-equities", "tags": [ "Employee Tables" ], "summary": "List the employee's equity grants.", "description": "Returns a list of equity grants for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of salary equity grants.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquityEntries" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-id-equities", "tags": [ "Employee Tables" ], "summary": "Creates a new equity grant for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Equity grant to add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquityEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry added successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" } }, "/people/{id}/equities/{entry_id}": { "put": { "operationId": "put_people-id-equities-entry-id", "tags": [ "Employee Tables" ], "summary": "Updates an equity grant for an employee", "description": "This endpoint updates an entry in the employee’s equity table.

    Note that the entire equities entry will be overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values).

    ", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to update.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquityEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry updated successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" }, "delete": { "operationId": "delete_people-id-equities-entry-id", "tags": [ "Employee Tables" ], "summary": "Deletes an equity grant for an employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The Entry ID to delete.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry deleted successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/variable": { "get": { "operationId": "get_people-id-variable", "tags": [ "Employee Tables" ], "summary": "List employee's variable payments", "description": "Returns a list of variable payments for a given employee.Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariableEntries" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-id-variable", "tags": [ "Employee Tables" ], "summary": "Creates a new variable payment for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Variable payment to add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVariableEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry added successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" } }, "/people/{id}/variable/{entry_id}": { "delete": { "operationId": "delete_people-id-variable-entry-id", "tags": [ "Employee Tables" ], "summary": "Deletes a variable payment record for an employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The Entry ID to delete.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry deleted successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/training": { "get": { "operationId": "get_people-id-training", "tags": [ "Employee Tables" ], "summary": "List the employee's training records.", "description": "Returns a list of training entries from the employee's Training table, for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "The identifier of the employee.", "required": true, "schema": { "type": "string" } }, { "name": "includeArchived", "in": "query", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of training entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingEntries" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-id-training", "tags": [ "Employee Tables" ], "summary": "Creates a new training records for a given employee", "description": "Create a new training record in the Training table. Follow the parameters description for more details on the values to pass to this endpoint.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Values for the Training entry you want to add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainingEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry added successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" } }, "/people/{id}/training/{entry_id}": { "delete": { "operationId": "delete_people-id-training-entry-id", "tags": [ "Employee Tables" ], "summary": "Deletes any training records for an employee.", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The Entry ID to delete.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry deleted successfully.", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/{id}/dependents": { "post": { "operationId": "post_people-id-dependents", "tags": [ "Employee Tables" ], "summary": "Create a dependent entry for an employee", "description": "Creates a new dependent entry for the employee. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration. On success, returns the new entry id. Creating or deleting dependents also updates the employee's `home.numberOfKids` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > Home > Manage selected employees' Home sections (or Children/Dependents table Manage when field-level permissions are enabled).", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Values for the dependent entry you want to add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDependentEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DependentEntryIdResponse" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry", "x-internal": false } }, "/people/{id}/dependents/{entry_id}": { "put": { "operationId": "put_people-id-dependents-entry-id", "tags": [ "Employee Tables" ], "summary": "Update a dependent entry for an employee", "description": "Updates an existing dependent entry for the given employee. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration. Returns no content on success.

    **Required permissions**: People's Data > Home > Manage selected employees' Home sections (or Children/Dependents table Manage when field-level permissions are enabled).", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to update.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "Values for the dependent entry you want to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DependentEntry" } } }, "required": true }, "responses": { "204": { "description": "Entry updated successfully." }, "404": { "description": "No dependent entry was found for the given employee and entry ID." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry", "x-internal": false }, "delete": { "operationId": "delete_people-id-dependents-entry-id", "tags": [ "Employee Tables" ], "summary": "Delete a dependent entry for an employee", "description": "Deletes a dependent entry for the given employee. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration. Returns no content on success. Also updates the employee's `home.numberOfKids` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > Home > Manage selected employees' Home sections (or Children/Dependents table Manage when field-level permissions are enabled).", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to delete.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Entry deleted successfully." }, "404": { "description": "No dependent entry was found for the given employee and entry ID." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-internal": false } }, "/people/{id}/right-to-work": { "post": { "operationId": "post_people-id-right-to-work", "tags": [ "Employee Tables" ], "summary": "Create a right to work entry for an employee", "description": "Creates a new right to work entry for the employee. On success, returns the new entry id. Creating, updating, or deleting entries also updates the employee's `financial.rightToWorkExpiryDate` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > Right to Work > Manage selected employees' Right to Work sections (or Right to Work table Manage when field-level permissions are enabled).", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Values for the right to work entry you want to add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRightToWorkEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RightToWorkEntryIdResponse" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry", "x-internal": false } }, "/people/{id}/right-to-work/{entry_id}": { "put": { "operationId": "put_people-id-right-to-work-entry-id", "tags": [ "Employee Tables" ], "summary": "Update a right to work entry for an employee", "description": "Updates an existing right to work entry for the given employee. Returns no content on success. Also updates the employee's `financial.rightToWorkExpiryDate` field.

    **Required permissions**: People's Data > Right to Work > Manage selected employees' Right to Work sections (or Right to Work table Manage when field-level permissions are enabled).", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to update.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "Values for the right to work entry you want to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RightToWorkEntry" } } }, "required": true }, "responses": { "204": { "description": "Entry updated successfully." }, "404": { "description": "No right to work entry was found for the given employee and entry ID." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry", "x-internal": false }, "delete": { "operationId": "delete_people-id-right-to-work-entry-id", "tags": [ "Employee Tables" ], "summary": "Delete a right to work entry for an employee", "description": "Deletes a right to work entry for the given employee. Returns no content on success. Also updates the employee's `financial.rightToWorkExpiryDate` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > Right to Work > Manage selected employees' Right to Work sections (or Right to Work table Manage when field-level permissions are enabled).", "parameters": [ { "name": "id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The entry ID to delete.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Entry deleted successfully." }, "404": { "description": "No right to work entry was found for the given employee and entry ID." } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-internal": false } }, "/people/{id}/bank-accounts": { "get": { "operationId": "get_people-id-bank-accounts", "tags": [ "Employee Tables" ], "summary": "List employee's bank accounts", "description": "

    Returns a list of the bank accounts table entries for a given employee.

    Important:
    The Bank Account details are listed under the 'Financial' category in Bob's UI. They include basic bank account details, and may include also a list of bank accounts (if using more than a single bank account).

    If you are using a list of Bank Accounts:
    Use this endpoint will fetch the list of bank accounts.
    Use the Read metadata for specific custom table endpoint and provide the table name: `bankAccounts` to fetch the table's metadata.

    If you are using only a single Bank Account:
    To fetch the basic bank account details (not the table), use the employee's search endpoint instead, and specify the fields you want to fetch (e.g. 'financial.bankName'). To learn more, see how to work with Fields, Custom fields and Lists.

    See the '200' response for the body response.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the employee for whom you want to fetch the bank account entries. The employee ID is returned in the 'id' field when retrieving an employee's data.
    For **testing purposes** you can obtain the Employee ID from the URL in the user interface.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of bank account entries.", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountsEntries" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-id-bank-accounts", "tags": [ "Employee Tables" ], "summary": "Create a new bank account entry for a given employee.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the employee for whom you want to add the bank account entry. The employee ID is returned in the 'id' field when retrieving an employee's data.
    For **testing purposes** you can obtain the Employee ID from the URL in the user interface.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The details of the bank account to add.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountsEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry created successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" } }, "/people/{id}/bank-accounts/{entry_id}": { "put": { "operationId": "put_people-id-bank-accounts-entry-id", "tags": [ "Employee Tables" ], "summary": "Update a bank account entry in the employee's bank accounts table.", "description": "This endpoint updates an entry in the employee’s Bank accounts table.
    The unique identifier for the bank account entry is the entry id. To obtain the employee's bank account entries use the GET /people/{employee-id}/bank-accounts endpoint.

    **Notes**:
    1. **Out-of-the-box columns**: These columns will be completely overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values). 2. **Custom columns**: These columns will remain unchanged unless explicitly included in the payload.

    ", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the employee for whom you want to update the bank account entry. The employee ID is returned in the 'id' field when retrieving an employee's data.
    For **testing purposes** you can obtain the Employee ID from the URL in the user interface.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The ID of the entry in the bank accounts table which you are updating. To obtain the bank account entry use the GET /people/{id}/bank-accounts endpoint.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountsEntry" } } }, "required": true }, "responses": { "200": { "description": "Entry updated successfully.", "content": {} }, "404": { "description": "Requested entry not found. Nothing was changed", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "body" }, "delete": { "operationId": "delete_people-id-bank-accounts-entry-id", "tags": [ "Employee Tables" ], "summary": "Deletes a bank account entry from a given employee's bank accounts table.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the employee for whom you want to delete the bank account entry. The employee ID is returned in the 'id' field when retrieving an employee's data.
    For **testing purposes** you can obtain the Employee ID from the URL in the user interface.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The ID of the entry in the bank accounts table which you want to delete. To obtain the bank account entry use the GET /people/{id}/bank-accounts endpoint.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Entry deleted successfully", "content": {} }, "404": { "description": "Requested entry not found. Nothing was changed", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/custom-tables/metadata": { "get": { "operationId": "get_people-custom-tables-metadata", "tags": [ "Custom Tables" ], "summary": "Read metadata of custom tables defined", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomTableMetadataList" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/custom-tables/metadata/{custom_table_id}": { "get": { "operationId": "get_people-custom-tables-metadata-custom-table-id", "tags": [ "Custom Tables" ], "summary": "Read metadata for specific custom table", "parameters": [ { "name": "custom_table_id", "in": "path", "description": "The ID of custom table.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomTableMetadata" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } }, "/people/custom-tables/{employee_id}/{custom_table_id}": { "get": { "operationId": "get_people-custom-tables-employee-id-custom-table-id", "tags": [ "Custom Tables" ], "summary": "Read all entries of the given custom table", "parameters": [ { "name": "employee_id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "custom_table_id", "in": "path", "description": "The ID of custom table.", "required": true, "schema": { "type": "string" } }, { "name": "includeHumanReadable", "in": "query", "description": "Whether to include the additional \"humanReadable\" JSON node in the response.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Has-Restricted-Columns": { "description": "Set to \"true\" when field-level permissions (FLP) has filtered columns from the response. Only present when FLP is enabled and the service user has partial column permissions. To learn more, see Field level permissions.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomTableEntriesList" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] }, "post": { "operationId": "post_people-custom-tables-employee-id-custom-table-id", "tags": [ "Custom Tables" ], "summary": "Create new custom table entry", "description": "Provide an array of columns and their values. Columns that are defined as **Mandatory** (from the custom column's settings) must be provided.
    Values can be any of the supported field types.

    **Note**: You can use **Examples > Request Example** option for a basic example, however, we recommend that you copy the endpoint to Postman and test more complicated structures using the JSON editor.", "parameters": [ { "name": "employee_id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "custom_table_id", "in": "path", "description": "The ID of custom table.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Array of column IDs and their values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomTableCreateEntriesList" }, "example": { "values": [ { "column_1663598152485": 5185395, "column_1663598024920": "2022-09-30", "column_1663597992534": "text area text area text area", "column_1663598062584": "252614471" } ] } } }, "required": true }, "responses": { "200": { "description": "Entry created successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "values" } }, "/people/custom-tables/{employee_id}/{custom_table_id}/{entry_id}": { "put": { "operationId": "put_people-custom-tables-employee-id-custom-table-id-entry-id", "tags": [ "Custom Tables" ], "summary": "Update custom table entry.", "description": "Provide an array of columns and their values.
    **Important**: Although this is a PUT method, it behaves like a PATCH request, meaning you only need to send the fields you want to update, and any other fields will remain unchanged.
    Values can be any of the supported field types.

    **Note**: You can use **Examples > Request Example** option for a basic example, however, we recommend that you copy the endpoint to Postman and test more complicated structures using the JSON editor.", "parameters": [ { "name": "employee_id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "custom_table_id", "in": "path", "description": "The ID of custom table.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The ID of custom table entry.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Array of column IDs and their values", "type": "array", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string" } ] } } }, "example": { "column_1663598152485": 5185395, "column_1663598024920": "2022-09-30", "column_1663597992534": "text area text area text area", "column_1663598062584": "252614471" } } }, "required": true }, "responses": { "200": { "description": "Entry updated successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ], "x-codegen-request-body-name": "entry" }, "delete": { "operationId": "delete_people-custom-tables-employee-id-custom-table-id-entry-id", "tags": [ "Custom Tables" ], "summary": "Delete custom table entry", "parameters": [ { "name": "employee_id", "in": "path", "description": "Employee ID.", "required": true, "schema": { "type": "string" } }, { "name": "custom_table_id", "in": "path", "description": "The ID of custom table.", "required": true, "schema": { "type": "string" } }, { "name": "entry_id", "in": "path", "description": "The ID of custom table entry.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entry deleted successfully", "content": {} } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } } }, "components": { "schemas": { "WebhookEvent": { "type": "object", "description": "Base webhook event structure containing common webhook properties", "properties": { "companyId": { "type": "number", "description": "The company ID" }, "type": { "type": "string", "description": "The event type (e.g., employee.created)" }, "triggeredBy": { "type": "string", "description": "The backend-id of the employee that triggered the event, or 'system' for system-triggered events" }, "triggeredAt": { "type": "string", "description": "The timestamp when the event occurred (ISO 8601-style string)" }, "version": { "type": "string", "description": "The webhook version (e.g., v2)" }, "data": { "type": "object", "description": "Event-specific payload; structure varies by event type" } }, "required": [ "companyId", "type", "triggeredBy", "triggeredAt", "version", "data" ] }, "EmployeeCreatedEventData": { "type": "object", "description": "Data payload for employee.created event", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" } }, "required": [ "employeeId" ] }, "EmployeeUpdatedEventData": { "type": "object", "description": "Data payload for employee.updated event", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "fieldUpdates": { "type": "array", "description": "The field IDs that were explicitly changed (calculated fields are not included)", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The field ID (e.g., personal.birthDate)" } } } } }, "required": [ "employeeId" ] }, "EmployeeDeletedEventData": { "type": "object", "description": "Data payload for employee.deleted event", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the deleted employee" }, "email": { "type": "string", "description": "The employee email (included since the record is no longer available after deletion)" } }, "required": [ "employeeId" ] }, "EmployeeLifecycleEventData": { "type": "object", "description": "Data payload for lifecycle events (joined, left, activated, inactivated, temporaryLeave)", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" } }, "required": [ "employeeId" ] }, "TableEntryEventData": { "type": "object", "description": "Data payload for table.entry.created and table.entry.updated events. Historical tables include `effectiveDate` only; non-historical tables include numeric `id` only. The other identifier is omitted from the JSON when not applicable.", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "tableId": { "type": "string", "description": "The table identifier (e.g., lifecycle, work, employment, salary, bankAccounts)" }, "effectiveDate": { "type": "string", "format": "date", "description": "Present for historical tables only. The effective date that identifies this row together with employeeId. Omitted for non-historical tables." }, "id": { "type": "integer", "description": "Present for non-historical tables only. The numeric ID of this table row when reading via the API. Omitted for historical tables." } }, "required": [ "employeeId", "tableId" ], "oneOf": [ { "required": [ "effectiveDate" ] }, { "required": [ "id" ] } ] }, "EmployeeCreatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.created" ], "description": "Event type for employee created" }, "data": { "$ref": "#/components/schemas/EmployeeCreatedEventData" } } } ] }, "EmployeeUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.updated" ], "description": "Event type for employee field updated" }, "data": { "$ref": "#/components/schemas/EmployeeUpdatedEventData" } } } ] }, "EmployeeDeletedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.deleted" ], "description": "Event type for employee deleted" }, "data": { "$ref": "#/components/schemas/EmployeeDeletedEventData" } } } ] }, "EmployeeJoinedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.joined" ], "description": "Event type for employee joined (access granted)" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeLeftEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.left" ], "description": "Event type for employee terminated or on Garden leave" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeActivatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.activated" ], "description": "Event type for employee access enabled" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeInactivatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.inactivated" ], "description": "Event type for employee inactivated (on leave or terminated)" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeTemporaryLeaveEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.temporaryLeave" ], "description": "Event type for employee on temporary leave" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "TableEntryCreatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table.entry.created" ], "description": "Event type for table entry created" }, "data": { "$ref": "#/components/schemas/TableEntryEventData" } } } ] }, "TableEntryUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table.entry.updated" ], "description": "Event type for table entry updated" }, "data": { "$ref": "#/components/schemas/TableEntryEventData" } } } ] }, "CurrencyValue": { "required": [ "currency", "value" ], "type": "object", "properties": { "value": { "type": "number", "format": "double" }, "currency": { "type": "string", "description": "Three-letter currency code." } } }, "TableEntry": { "required": [ "effectiveDate" ], "type": "object", "properties": { "id": { "type": "integer", "description": "ID." }, "reason": { "type": "string", "description": "The reason for this change." }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" } } }, "WorkTableEntry": { "required": [ "effectiveDate" ], "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the work entry." }, "reason": { "type": "string", "description": "The reason for this change." }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" } } }, "SalaryEntry": { "allOf": [ { "type": "object", "properties": { "canBeDeleted": { "type": "boolean", "description": "internal flag" }, "workChangeType": { "type": "string", "description": "The type of the change that was performed for this work entry. This will contain the ID of the value from the Change Type list." }, "change": { "type": "object", "description": "Details of the last change and the ID of the user who updated this entry", "properties": { "reason": { "type": "string" }, "changedBy": { "type": "string" }, "changedById": { "type": "string" } } }, "payFrequency": { "type": "string", "description": "Represents the frequency the salary is paid. This can be one of: Monthly, Semi Monthly, Weekly, or Bi-Weekly." }, "creationDate": { "type": "string", "description": "The date this entry was created.", "format": "date" }, "isCurrent": { "type": "boolean", "description": "Is 'true' when this is the effective entry which is currently active." }, "modificationDate": { "type": "string", "description": "The date this entry was modified.", "format": "date" }, "id": { "type": "integer", "description": "The id of the entry." }, "endEffectiveDate": { "type": "string", "description": "For entries that are not active - this is the date this entry became not effective.", "format": "date" }, "activeEffectiveDate": { "type": "string", "description": "The active effective date for this entry.", "format": "date" }, "customColumns": { "type": "object", "properties": {}, "description": "If the table has custom columns, they will appear here." }, "base": { "$ref": "#/components/schemas/CurrencyValue" }, "payPeriod": { "type": "string", "description": "Represents the period for this salary entry. This can be one of: Annual, Hourly, Daily, Weekly, Monthly." }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective. This is a mandatory field for a work entry.", "format": "date" } } } ], "required": [ "base", "payPeriod" ] }, "SalaryEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/SalaryEntry" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "EquityEntry": { "allOf": [ { "$ref": "#/components/schemas/TableEntry" }, { "type": "object", "properties": { "quantity": { "type": "number", "description": "The number of equities granted.", "format": "double" }, "equityType": { "type": "string", "description": "The type of the grant." }, "vestingCommencementDate": { "type": "string", "description": "Vesting commencement date.", "format": "date" }, "consentNumber": { "type": "string", "description": "Consent number." }, "grantDate": { "type": "string", "description": "Date the equity was granted.", "format": "date" }, "optionExpiration": { "type": "string", "description": "Date the options expire.", "format": "date" }, "exercisePrice": { "$ref": "#/components/schemas/CurrencyValue" }, "vestingTerm": { "type": "string", "description": "Terms for exercising this grant." }, "grantType": { "type": "string", "description": "Grant type. One of: Initial Grant, Merit Grant" }, "vestingSchedule": { "type": "number", "description": "The vesting schedule ID assigned to this grant.", "format": "long" }, "grantNumber": { "type": "number", "description": "The Grant number for employee.", "format": "double" }, "grantStatus": { "type": "string", "description": "Grant status. one of: Granted, Pending Approval" } } } ], "required": [ "quantity", "equityType" ] }, "EquityEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/EquityEntry" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "ReadVariableEntry": { "type": "object", "properties": { "id": { "type": "number", "description": "The identifier of the entry in the Variable Pay table" }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" }, "endEffectiveDate": { "type": "string", "description": "For entries that are not active - this is the date this entry became not effective.", "format": "date" }, "isCurrent": { "type": "boolean", "description": "Indicates whether this is the 'current' row (effective date is current)" }, "canBeDeleted": { "type": "boolean" }, "amount": { "$ref": "#/components/schemas/CurrencyValue" }, "departmentPercent": { "type": "number", "description": "The employee's department on-target weight, in percentage." }, "individualPercent": { "type": "number", "description": "The employee's individual on-target weight, in percentage." }, "payoutType": { "type": "string", "description": "The variable pay type - currenly only \"amount\" is supported." }, "variableType": { "type": "string", "description": "The type of variable pay. Can be any of: \"Bonus\", \"ExecutiveBonus\", \"Commission\"." }, "paymentPeriod": { "type": "string", "description": "This represents the period for this variable entry. It can be one of: Annual, Half-Yearly, Quarterly, Monthly." }, "creationDate": { "type": "string", "description": "The date the variable pay entry was created.", "format": "date" }, "endDate": { "type": "string", "description": "The date of variable pay completion.", "format": "date" }, "modificationDate": { "type": "string", "description": "The date the variable pay entry was updated.", "format": "date" }, "percentageOfAnnualSalary": { "type": "number", "description": "Calculated field (not supported at the moment via the API)" }, "companyPercent": { "type": "number", "description": "The employee's company on-target weight, in percentage." }, "customColumns": { "type": "object", "properties": {} }, "change": { "type": "object", "description": "Details of the last change and the ID of the user who updated this entry", "properties": { "reason": { "type": "string" }, "changedBy": { "type": "string" }, "changedById": { "type": "string" } } } } }, "CreateVariableEntry": { "type": "object", "properties": { "effectiveDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" }, "amount": { "$ref": "#/components/schemas/CurrencyValue" }, "variableType": { "type": "string", "description": "The variable pay type - currently only \"amount\" is supported." }, "paymentPeriod": { "type": "string", "description": "This represents the period for this variable entry. It can be one of: Annual, Half-Yearly, Quarterly, Monthly." }, "companyPercent": { "type": "number", "description": "The employee's company on-target weight, in percentage." }, "departmentPercent": { "type": "number", "description": "The employee's department on-target weight, in percentage." }, "individualPercent": { "type": "number", "description": "The employee's individual on-target weight, in percentage." }, "reason": { "type": "string", "description": "The reason for this change." } }, "required": [ "amount", "effectiveDate", "variableType", "paymentPeriod" ] }, "VariableEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/ReadVariableEntry" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "TrainingEntry": { "allOf": [ { "type": "object", "properties": { "id": { "type": "number", "description": "The id of the training entry. If not passed, the system will assign a backend-id." }, "name": { "type": "string", "description": "The backend-id of the relevant entry in the Training Name list. To find out the list items backend-ids, use the Lists metadata endpoint to fetch the `TraningName` list. Note that the backend-ids may consist of out-of-the-box list items which will be represented as strings (like 'Training'), or a numeric value for user-defined items. To learn more, see Fields and lists metadata." }, "description": { "type": "string", "description": "Further description about the training entry." }, "cost": { "$ref": "#/components/schemas/CurrencyValue" }, "status": { "type": "string", "description": "The status of the training entry" }, "frequency": { "type": "string", "description": "The frequency of the training entry. The name must be of \"Once\", \"Weekly\", \"Monthly\", \"Yearly\". This is an item in the frequency list." }, "startDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" }, "endDate": { "type": "string", "description": "The date of training completion.", "format": "date" }, "documentId": { "type": "number", "description": "ID of the document attached to this training entry.", "format": "long" }, "customColumns": { "type": "object", "properties": {} } } } ], "required": [ "amount", "type", "paymentPeriod" ] }, "TrainingEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/TrainingEntry" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "CreateDependentEntry": { "type": "object", "description": "Request body for creating a dependent entry. Do not send `id`; the system assigns it on create.", "properties": { "firstName": { "type": "string", "description": "Dependent's first name." }, "surname": { "type": "string", "description": "Dependent's surname / last name." }, "birthDate": { "type": "string", "format": "date", "description": "Dependent's date of birth (ISO 8601 date)." }, "gender": { "type": "string", "description": "Dependent's gender value as stored in Bob." }, "customColumns": { "type": "object", "properties": {}, "description": "Custom column values for this entry, keyed by column id." } } }, "DependentEntry": { "type": "object", "description": "A dependent (children/dependents table) entry as returned in reads.", "properties": { "id": { "type": "integer", "format": "int64", "description": "The id of the dependent entry. Assigned by the system on create." }, "firstName": { "type": "string", "description": "Dependent's first name." }, "surname": { "type": "string", "description": "Dependent's surname / last name." }, "birthDate": { "type": "string", "format": "date", "description": "Dependent's date of birth (ISO 8601 date)." }, "gender": { "type": "string", "description": "Dependent's gender value as stored in Bob." }, "customColumns": { "type": "object", "properties": {}, "description": "Custom column values for this entry, keyed by column id." } } }, "DependentEntryIdResponse": { "type": "object", "required": [ "entryId" ], "properties": { "entryId": { "type": "integer", "format": "int64", "description": "The id of the newly created dependents table entry." } } }, "CreateRightToWorkEntry": { "type": "object", "description": "Request body for creating a right to work entry. Do not send `id`; the system assigns it on create.", "properties": { "type": { "type": "string", "description": "Right to work document type (list value as stored in Bob)." }, "documentId": { "type": "number", "format": "long", "description": "ID of the document attached to this entry. Upload files via the Docs API and reference the returned document id here." }, "expirationDate": { "type": "string", "format": "date", "description": "Document expiration date (ISO 8601 date)." }, "number": { "type": "string", "description": "Document or permit number." }, "issuedBy": { "type": "string", "description": "Issuing authority." }, "validFrom": { "type": "string", "format": "date", "description": "Date from which the document is valid (ISO 8601 date)." }, "applicationDate": { "type": "string", "format": "date", "description": "Application date (ISO 8601 date)." }, "customColumns": { "type": "object", "properties": {}, "description": "Custom column values for this entry, keyed by column id." } } }, "RightToWorkEntry": { "type": "object", "description": "A right to work table entry as returned in reads.", "properties": { "id": { "type": "integer", "format": "int64", "description": "The id of the right to work entry. Assigned by the system on create." }, "type": { "type": "string", "description": "Right to work document type (list value as stored in Bob)." }, "documentId": { "type": "number", "format": "long", "description": "ID of the document attached to this entry." }, "expirationDate": { "type": "string", "format": "date", "description": "Document expiration date (ISO 8601 date)." }, "number": { "type": "string", "description": "Document or permit number." }, "issuedBy": { "type": "string", "description": "Issuing authority." }, "validFrom": { "type": "string", "format": "date", "description": "Date from which the document is valid (ISO 8601 date)." }, "applicationDate": { "type": "string", "format": "date", "description": "Application date (ISO 8601 date)." }, "customColumns": { "type": "object", "properties": {}, "description": "Custom column values for this entry, keyed by column id." } } }, "RightToWorkEntryIdResponse": { "type": "object", "required": [ "entryId" ], "properties": { "entryId": { "type": "integer", "format": "int64", "description": "The id of the newly created right to work table entry." } } }, "WorkingPatternHourly": { "type": "object", "properties": { "workingPatternType": { "type": "string", "example": "hourly" }, "days": { "type": "object", "properties": { "sunday": { "type": "number", "example": 0 }, "monday": { "type": "number", "example": 9 }, "tuesday": { "type": "number", "example": 9 }, "wednesday": { "type": "number", "example": 9 }, "thursday": { "type": "number", "example": 9 }, "friday": { "type": "number", "example": 9 }, "saturday": { "type": "number", "example": 0 } } }, "hoursPerDay": { "type": "number", "example": 9 }, "workingPatternId": { "type": "number", "example": 0 } } }, "WorkingPatternBiWeekly": { "type": "object", "properties": { "workingPatternType": { "type": "string", "example": "fortnightly" }, "firstWeek": { "type": "object", "properties": { "sunday": { "type": "number", "example": 0 }, "monday": { "type": "number", "example": 9 }, "tuesday": { "type": "number", "example": 9 }, "wednesday": { "type": "number", "example": 9 }, "thursday": { "type": "number", "example": 9 }, "friday": { "type": "number", "example": 9 }, "saturday": { "type": "number", "example": 0 } } }, "secondWeek": { "type": "object", "properties": { "sunday": { "type": "number", "example": 0 }, "monday": { "type": "number", "example": 9 }, "tuesday": { "type": "number", "example": 9 }, "wednesday": { "type": "number", "example": 9 }, "thursday": { "type": "number", "example": 9 }, "friday": { "type": "number", "example": 9 }, "saturday": { "type": "number", "example": 0 } } }, "hoursPerDay": { "type": "number", "example": 9 }, "workingPatternId": { "type": "number", "example": 0 } } }, "WorkingPatternFlexible": { "type": "object", "properties": { "workingPatternType": { "type": "string", "example": "flexible" }, "weeklyWorkPercentage": { "type": "number", "example": 80 } } }, "WorkingPatternEntry": { "oneOf": [ { "$ref": "#/components/schemas/WorkingPatternHourly" }, { "$ref": "#/components/schemas/WorkingPatternBiWeekly" }, { "$ref": "#/components/schemas/WorkingPatternFlexible" } ] }, "EmploymentEntry": { "allOf": [ { "$ref": "#/components/schemas/TableEntry" }, { "type": "object", "properties": { "personalWorkingPatternType": { "type": "string", "description": "indicates whether the working pattern personal (adjusted). Can be null (no personal defined), \"custom\", \"library\" or \"flexible\"." }, "actualWorkingPattern": { "description": "The active working pattern for this entry. It will hold the pattern that is selected, no matter which type it is.", "allOf": [ { "$ref": "#/components/schemas/WorkingPatternEntry" } ] }, "standardWorkingPattern": { "description": "The working pattern that was selected from the library as standard. If null this means the standard is using the site default.", "type": "object", "example": null }, "standardWorkingPatternId": { "description": "The working pattern ID that was selected from the library as standard.", "type": "number", "example": null }, "workingPattern": { "description": "The personalized (adjusted) working pattern.", "type": "object", "example": null }, "siteWorkingPattern": { "description": "The site's default working pattern (always a weekly pattern).", "allOf": [ { "$ref": "#/components/schemas/WorkingPatternHourly" } ] }, "hoursInDayNotWorked": { "type": "number", "description": "Based on the actual working pattern" }, "weeklyHours": { "type": "number", "description": "Based on the actual working pattern" }, "fte": { "description": "the FTE percentage for this entry as calculated based on the working pattern", "type": "number" }, "calendarName": { "type": "string", "description": "The selected Holiday calendar" }, "calendarId": { "type": "integer", "description": "The selected Holiday calendar" }, "contract": { "type": "string", "description": "Contract, can be Full-Time, Part-Time, Shifts" }, "type": { "type": "string", "description": "Type as appears in the Employment Type list. Can be Permanent, Temporary, Apprentice, Contractor or any custom value." }, "salaryPayType": { "type": "string", "description": "Salary pay type, can be Salaries or Hourly." }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" }, "endEffectiveDate": { "type": "string", "description": "For entries that are not active - this is the date this entry became not effective.", "format": "date" }, "activeEffectiveDate": { "type": "string", "description": "The effective date of the active working pattern.", "format": "date" }, "isCurrent": { "type": "boolean", "description": "Is 'true' when this is the effective entry which is currently active." }, "canBeDeleted": { "type": "boolean" }, "modificationDate": { "type": "string", "description": "The date this entry was modified.", "format": "date" }, "CreationDate": { "type": "string", "description": "The date this entry was created.", "format": "date" }, "flsaCode": { "type": "string", "description": "FLSA code, can be Exempt or Non-Exempt." }, "change": { "type": "object", "description": "Details of the last change and the ID of the user who updated this entry", "properties": { "reason": { "type": "string" }, "changedBy": { "type": "string" }, "changedById": { "type": "string" } } } } } ], "required": [ "effectiveDate" ] }, "EmploymentEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/EmploymentEntry" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "WorkEntryForGet": { "type": "object", "properties": { "canBeDeleted": { "type": "boolean", "description": "internal flag" }, "workChangeType": { "type": "string", "description": "The type of the change that was performed for this work entry. This will contain the ID of the value from the Change Type list." }, "change": { "type": "object", "description": "Details of the last change and the ID of the user who updated this entry", "properties": { "reason": { "type": "string" }, "changedBy": { "type": "string" }, "changedById": { "type": "string" } } }, "reportsTo": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "The manager's employee ID (the email of the manager or a custom field containing the ID)." }, "firstName": { "type": "string", "description": "The manager's first name." }, "surname": { "type": "string", "description": "The manager's surname." }, "email": { "type": "string", "description": "The manager's email address." }, "displayName": { "type": "string", "description": "The manager's display name." } } }, "creationDate": { "type": "string", "description": "The date this entry was created effective.", "format": "date" }, "title": { "type": "string", "description": "The job title of the employee for this work entry. This field containe the ID of the job title entry from the job title list." }, "customColumns": { "type": "object", "properties": {} }, "isCurrent": { "type": "boolean", "description": "An indication whether this is the current active entry." }, "modificationDate": { "type": "string", "description": "The date this entry was created effective.", "format": "date" }, "site": { "type": "string", "description": "The site of the employee." }, "siteId": { "type": "integer", "description": "The id of the site of the employee." }, "id": { "type": "integer", "description": "The id of the entry." }, "endEffectiveDate": { "type": "string", "description": "For entries that are not active - this is the date this entry became not effective.", "format": "date" }, "activeEffectiveDate": { "type": "string", "description": "The active effective date for this entry.", "format": "date" }, "department": { "type": "string", "description": "The department the employee belonged to for this work entry. This field should contain the ID of the department entry in department list." }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective. This is a mandatory field for a work entry.", "format": "date" } } }, "WorkEntry": { "allOf": [ { "$ref": "#/components/schemas/WorkTableEntry" }, { "type": "object", "properties": { "title": { "type": "string", "description": "The job title of the employee for this work entry. This field should contain the ID of the job title entry from the job title list." }, "department": { "type": "string", "description": "The department the employee belonged to for this work entry. This field should contain the ID of the department entry in department list." }, "site": { "type": "string", "description": "The site of the employee. This is a mandatory field for a work entry (you must pass either the site or the siteId)." }, "siteId": { "type": "integer", "description": "The id of the site of the employee. This is a mandatory field for a work entry (you must pass either the site or the siteId)." }, "reportsTo": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "The manager's employee ID (the email of the manager or a custom field containing the ID)." }, "firstName": { "type": "string", "description": "The manager's first name." }, "surname": { "type": "string", "description": "The manager's surname." }, "email": { "type": "string", "description": "The manager's email address." }, "displayName": { "type": "string", "description": "The manager's display name." } }, "description": "The manager's details." }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective. This is a mandatory field for a work entry.", "format": "date" }, "customColumns": { "type": "object", "properties": {} } } }, { "type": "object" } ] }, "WorkEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/WorkEntryForGet" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "BankAccountsEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountsEntryForGet" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "BankAccountsEntryForGet": { "allOf": [ { "$ref": "#/components/schemas/BankAccountsEntry" }, { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier for the bank account entry." }, "changedBy": { "type": "string", "description": "The employee ID of the person who last modified this entry." } } } ] }, "BankAccountsEntry": { "type": "object", "properties": { "bankAccountType": { "type": "string", "enum": [ "Checking", "Savings" ], "description": "The list of bank accounts type comes with the above out-of-the-box values. To obtain additional user-defined values, you should fetch the list values call the Get all company lists Metadata API with `bankaccounttype` in the listname path parameter." }, "routingNumber": { "type": "string", "description": "The routing number indicates what bank this account is held in. Relevant for US and Canada." }, "accountNickname": { "type": "string", "description": "The nickname in Bob to easily identify and personalize this account in Online Banking." }, "accountNumber": { "type": "string", "description": "The account number is the unique identifier at this bank." }, "bankName": { "type": "string", "description": "The name of the specific financial institution." }, "branchAddress": { "type": "string", "description": "The bank's address." }, "bicOrSwift": { "type": "string", "description": "The SWIFT Address assigned to the bank in order to send automated international transfers." }, "iban": { "type": "string", "description": "The international bank account number (IBAN) for international transfers." }, "allocation": { "type": "string", "enum": [ "percent", "amount", "remaining" ], "description": "The salary portion allocated for this account. It can be defined as a percentage of the salary, as a fixed amount, or to allocate all of the remaining funds. The list of possible values cannot be modified. The values that correspond to this field should be provided in the 'amount' field." }, "amount": { "type": "number", "description": "Use this field to provide the values that correspond to the ‘allocation’ field. If allocation is 'percent' this value represents the percentage of the salary portion to allocate. If allocation is 'amount' this value represents the fixed amount of the salary portion to allocate. If allocation is 'remaining' then the amount field should remain empty. This indicates that all of the remaining funds will be allocated to this account." }, "useForBonus": { "type": "boolean", "description": "An indication whether this bank account is used for bonuses." } } }, "ActualPaymentsSearchRequest": { "type": "object", "required": [ "filters" ], "properties": { "filters": { "type": "array", "description": "

    An array of filter criteria, each containing a field ID, operator, and values. Supported fields for filtering are:

    Important: The array must include a filter for employeeId, as it is required for all requests.
    The structure of the filters may vary slightly depending on the field being used.

    ", "items": { "oneOf": [ { "type": "object", "title": "Employee ID filter", "description": "Comma-separated list of employee IDs to filter by. Each call can retrieve up to 200 employees.", "required": [ "fieldPath", "operator", "values" ], "properties": { "fieldPath": { "type": "string", "example": "employeeId", "description": "The identifier of the employeeId field." }, "operator": { "type": "string", "enum": [ "equals" ], "example": "equals", "description": "The comparison operator for the employee IDs." }, "values": { "type": "array", "items": { "type": "string", "example": "100001" }, "description": "A comma-separated list of employeeIDs to fetch by. For example: \"100001,200001\". Each call can retrieve up to 200 employees." } } }, { "type": "object", "title": "Pay date filter", "description": "payDate to filter by", "required": [ "fieldPath", "operator", "value" ], "properties": { "fieldPath": { "type": "string", "example": "payDate", "description": "The payDate field ID to filter by." }, "operator": { "type": "string", "enum": [ "greaterThanOrEquals", "lessThanOrEquals" ], "example": "greaterThanOrEquals", "description": "The comparison operator when filtering by date." }, "value": { "type": "string", "example": "2020-01-01", "description": "The date value to compare against." } } } ] } }, "pagination": { "type": "object", "description": "Optional pagination parameters.", "properties": { "limit": { "description": "Specifies the number of table entries to include on each page of the results. Defaults to 50 if not supplied.", "type": "number", "minimum": 1, "default": 50, "maximum": 200 }, "cursor": { "description": "A marker representing the first item on the next page to read. Should not be provided in the first call. To learn more, see Pagination in Bob's API.", "type": "string", "example": "" } }, "required": [ "limit" ], "example": { "limit": 50 } }, "includeArchived": { "type": "boolean", "description": "By default (false), archived columns are excluded from the response. When set to true, archived columns are included.", "default": false } } }, "ActualPaymentsSearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string", "example": "10001" }, "id": { "type": "number", "description": "The backend-ID of the actual payment table entry", "example": 11111 }, "payDate": { "type": "string", "format": "date" }, "payType": { "type": "string", "enum": [ "Bonus", "Executive bonus", "Commission" ], "example": "Bonus", "description": "The list of payment types comes with the above out-of-the-box values. To obtain additional user-defined values, you should fetch the list values call the Get all company lists Metadata API with `payType` in the listname path parameter." }, "amount": { "$ref": "#/components/schemas/CurrencyValue" }, "change": { "type": "object", "properties": { "reason": { "type": "string" }, "changedBy": { "type": "string" }, "changedById": { "type": "string" } } }, "customColumns": { "type": "object" } } } }, "response_metadata": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page." } } } } }, "LifeCycleEntry": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the lifecycle entry." }, "effectiveDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" }, "status": { "type": "string", "description": "Can be any of the employee lifecycle status in Bob (such as \"Hired\", \"Employed\", \"Terminated\", \"Garden leave\", \"Leave\",\"Parental leave\")." }, "employeeStatus": { "type": "string", "description": "This is the employee's **access status**, which is automatically determined when updating the status. It can be \"Active\", or \"Inactive\"" }, "workChangeType": { "type": "string", "description": "The type of the change that was performed for this work entry. This will contain the ID of the value from the Change Type list." }, "change": { "type": "object", "description": "Details of the last change and the ID of the user who updated this entry", "properties": { "reason": { "type": "string" }, "changedBy": { "type": "string" }, "changedById": { "type": "string" } } }, "creationDate": { "type": "string", "description": "The date this entry was created.", "format": "date" }, "reasonType": { "type": "string", "description": "The ID of the 'lifecycleReasonType' list entry" }, "isCurrent": { "type": "boolean", "description": "Is 'true' when this is the effective entry which is currently active." }, "modificationDate": { "type": "string", "description": "The date this entry was modified.", "format": "date" }, "leaveReason": { "type": "string", "description": "Can be any of" }, "endEffectiveDate": { "type": "string", "description": "For entries that are not active - this is the date this entry became not effective." }, "canBeDeleted": { "type": "boolean", "description": "internal flag" }, "customColumns": { "type": "object", "properties": {}, "description": "If the table has custom columns, they will appear here." } } }, "LifeCycleEntries": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/LifeCycleEntry" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "ReadEmployeesRequestReference": { "type": "object", "properties": { "fields": { "type": "array", "description": "Optional field IDs to return (max 400). Dot notation from Fields metadata (e.g. root.id). Omit for the default field set. See Critical behaviors below on this page.", "items": { "type": "string" }, "example": [ "root.id", "root.firstName" ] }, "filters": { "type": "array", "description": "Optional. One filter on root.id or root.email with operator equals. Omit when not filtering. See Critical behaviors below on this page.", "items": { "$ref": "#/components/schemas/EmployeeFilter" } }, "showInactive": { "type": "boolean", "default": false, "description": "Include inactive (typically terminated/former) employees. Default false (active only). See Critical behaviors below on this page.", "example": false }, "humanReadable": { "type": "string", "default": "", "description": "A flag that determines the data format to be returned in the response payload. Use this flag to convert \"machine format\" numeric IDs, such as \"1644513820829\" to the \"human readable\" values.

    Flag values:

    If not sent: will return only machine-format values. If you pass an invalid value it will be ignored and consdiered empty.

    Possible values:

    APPEND - include the additional \"humanReadable\" JSON node in the response.

    REPLACE - supply only humanReadable values in the JSON response instead of machine-readable values.
    " } }, "default": { "fields": [ "root.id", "root.firstName" ], "showInactive": false, "humanReadable": "", "filters": [ { "fieldPath": "root.id", "operator": "equals", "values": [ "3332883884017713938", "3332883909410030364" ] } ] } }, "ReadSingleEmployeeRequestReference": { "type": "object", "properties": { "fields": { "type": "array", "description": "An optional list of field IDs to return. Use dot notation as returned by Fields metadata (e.g. root.id, work.department). This is the canonical field ID. When not specified, a default set of fields and categories are returned including:
  • Basic employee fields like: name, id, avatar URL, creation date, etc.
  • Basic categories:
    • \n \n
    Fields without service-user permission or with unknown IDs are silently omitted (200 OK). Response keys use slash notation (e.g. /root/id). See People read API contract.
    The complete fields schema is described in the 200 response status section.", "items": { "type": "string" }, "example": [ "root.id", "root.firstName" ] }, "humanReadable": { "type": "string", "default": ".", "description": "A flag that determines the data format to be returned in the response payload. Use this flag to convert \"machine format\" numeric IDs, such as \"1644513820829\" to the \"human readable\" values.

    Flag values:

    If not sent: will return only machine-format values. If you pass an invalid value it will be ignored and consdiered empty.

    Possible values:

    APPEND - include the additional \"humanReadable\" JSON node in the response.

    REPLACE - supply only humanReadable values in the JSON response instead of machine-readable values.
    " } } }, "EmployeeFilter": { "type": "object", "properties": { "fieldPath": { "type": "string", "enum": [ "root.id", "root.email" ], "example": "root.id", "description": "The field ID to filter by (dot notation, as returned by Fields metadata). Supported values: root.id, root.email. Any other field ID returns 400 HTTP error." }, "operator": { "type": "string", "example": "equals", "description": "Supported operators: “equals”
    Any other operator will get a response of 400 HTTP error." }, "values": { "type": "array", "description": "The list of values to compare with the operator. An Empty list will result in 400 HTTP error.", "items": { "type": "string" }, "example": [ "", "" ] } } }, "AboutPart": { "type": "object", "properties": { "avatar": { "type": "string", "description": "Image URL of the employee's avatar." }, "hobbies": { "type": "array", "description": "An array of the employee's hobbies.", "items": { "type": "string" } }, "foodPreferences": { "type": "array", "description": "An array of the employee's food preferences.", "items": { "type": "string" } }, "socialData": { "type": "object", "description": "Employee's social data.", "properties": { "linkedin": { "type": "string" }, "twitter": { "type": "string" }, "facebook": { "type": "string" } } }, "superpowers": { "type": "string", "description": "Employee's super powers." } } }, "PersonalPart": { "type": "object", "properties": { "honorific": { "type": "string", "description": "The employee's title, This can be Mr, Mrs. Ms. etc." }, "shortBirthDate": { "type": "string" }, "nationality": { "description": "A list of countries in which the employee has citizenship.", "type": "array", "items": { "type": "string" } }, "pronouns": { "type": "string", "description": "One of Male / Female." } } }, "WorkPartReadable": { "type": "object", "properties": { "shortStartDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "startDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "manager": { "type": "string", "description": "The full name of the employee's manager." }, "tenureDuration": { "type": "string", "description": "The tenure duration of the employee." }, "durationOfEmployment": { "type": "string", "description": "The tenure duration of the employee." }, "reportsToIdInCompany": { "type": "string", "description": "The ID in company of the manager." }, "employeeIdInCompany": { "type": "string", "description": "The ID of the manager." }, "reportsTo": { "type": "string", "description": "The full name of the person the employee reports to." }, "tenureDurationYears": { "type": "string", "description": "The tenture duration in years." }, "department": { "type": "string", "description": "The department this employee belong to." }, "siteID": { "type": "string", "description": "The ID of the site the employee belongs to." }, "tenureYears": { "type": "string", "description": "The tenture in years." }, "isManager": { "type": "string", "description": "Is the employee a manager (Yes/No)." }, "title": { "type": "string", "description": "The employee's title." }, "site": { "type": "string", "description": "The employee's site." }, "originalStartDate": { "type": "string", "description": "The original date the employee started to work" }, "activeEffectiveDate": { "type": "string", "description": "The active effective date the employee started to work" }, "secondLevelManager": { "type": "string", "description": "The full name of the manager in the second level" }, "daysOfPreviousService": { "type": "string", "description": "The number of days in previous service" }, "yearsOfService": { "type": "string", "description": "The number of years in service" } } }, "AboutPartReadable": { "type": "object", "properties": { "foodPreferences": { "type": "string", "description": "Employee's food preferences." }, "superpowers": { "type": "string", "description": "Employee's super powers." }, "hobbies": { "type": "string", "description": "A list of the employee's hobbies." }, "about": { "type": "string", "description": "Employee's about sentence." }, "avatar": { "type": "string", "description": "Image URL of the employee's avatar." } } }, "WorkPartMachineFormat": { "type": "object", "properties": { "shortStartDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "startDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "manager": { "type": "string", "description": "The full name of the employee's manager." }, "tenureDuration": { "type": "object", "description": "The tenure duration of the employee.", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } }, "custom": { "description": "The custom fields of the employee.", "type": "array", "items": { "type": "string" } }, "durationOfEmployment": { "type": "object", "description": "The tenure duration of employment of the employee.", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } }, "reportsToIdInCompany": { "type": "number", "description": "The ID in company of the manager." }, "employeeIdInCompany": { "type": "number", "description": "The ID of the manager." }, "reportsTo": { "type": "object", "description": "The full name of the person the employee reports to.", "properties": { "displayName": { "type": "string" }, "email": { "type": "string" }, "surname": { "type": "string" }, "firstName": { "type": "string" }, "id": { "type": "string" } } }, "workMobile": { "type": "string", "description": "The work mobile number." }, "workPhone": { "type": "string", "description": "The work phone number." }, "indirectReports": { "type": "number", "description": "The person this employee reports to indirectly." }, "siteID": { "type": "number", "description": "The ID of the site the employee belongs to." }, "tenureDurationYears": { "type": "number", "description": "The tenture duration in years." }, "department": { "type": "string", "description": "The department this employee belong to." }, "tenureYears": { "type": "number", "description": "The tenture in years." }, "isManager": { "type": "string", "description": "Is the employee a manager (Yes/No)." }, "title": { "type": "string", "description": "The employee's title." }, "site": { "type": "string", "description": "The employee's site." }, "originalStartDate": { "type": "string", "description": "The original date the employee started to work" }, "activeEffectiveDate": { "type": "string", "description": "The active effective date the employee started to work" }, "directReports": { "type": "number", "description": "The internal ID of the person this employee reports to directly" }, "secondLevelManager": { "type": "string", "description": "The ID of the manager in the second level" }, "daysOfPreviousService": { "type": "number", "description": "The number of days in previous service" }, "yearsOfService": { "type": "number", "description": "The number of years in service" } } }, "AboutPartMachineFormat": { "type": "object", "properties": { "foodPreferences": { "type": "array", "description": "Employee's food preferences.", "items": { "type": "string" } }, "socialData": { "type": "object", "description": "Employee's social data.", "properties": { "linkedin": { "type": "string" }, "twitter": { "type": "string" }, "facebook": { "type": "string" } } }, "superpowers": { "type": "array", "description": "Employee's super powers.", "items": { "type": "string" } }, "hobbies": { "type": "array", "description": "A list of the employee's hobbies.", "items": { "type": "string" } }, "about": { "type": "string", "description": "Employee's about sentence." }, "avatar": { "type": "string", "description": "Image URL of the employee's avatar." } } }, "CreateEmployeeRequest": { "required": [ "email", "firstName", "surname", "work" ], "type": "object", "properties": { "firstName": { "type": "string", "example": "Joe", "description": "Employee's first name. Max length: 50, can only contain letters and `´`̀_-;,̩.\\/'’\"()`\n" }, "surname": { "type": "string", "example": "Doe", "description": "Employee's surname. Max length: 50, can only contain letters and `´`̀_-;,̩.\\/'’\"()`\n" }, "email": { "type": "string", "example": "joe.doe@examplecompany.com", "description": "Employee's email address. Must be a valid email address, unique within the company", "format": "email" }, "work": { "required": [ "site", "startDate" ], "type": "object", "properties": { "site": { "type": "string", "example": "New York", "description": "The employee's site. Must be a valid list-item from the `site` list (use the display value, not the backend-id)" }, "startDate": { "type": "string", "example": "2024-01-01", "description": "The employee's employment start date - format: YYYY-MM-DD\n", "format": "date" }, "department": { "type": "string", "example": "Accounting", "description": "The department the employee belonged to for this work entry. Must be a valid list-item from the `department` list." }, "title": { "type": "string", "example": "Chief Engineer", "description": "The job title for the employee for this work entry. Must be a valid list-item from the `title` list" } } } } }, "EmployeeTermination": { "required": [ "terminationDate" ], "type": "object", "properties": { "terminationDate": { "type": "string", "description": "The employee's termination date", "format": "date" }, "terminationReason": { "type": "string", "description": "The ID of the 'terminationReason' list entry" }, "reasonType": { "type": "string", "description": "The ID of the 'lifecycleReasonType' list entry" }, "noticePeriod": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "days", "weeks", "month", "years" ] }, "length": { "type": "integer" } }, "description": "Notice period length" }, "lastDayOfWork": { "type": "string", "format": "date" } }, "example": { "terminationDate": "2025-09-23", "noticePeriod": { "unit": "days", "length": 30 }, "lastDayOfWork": "2025-09-22", "terminationReason": "Redundant", "reasonType": "End of Contract" } }, "EmployeeResponseReadable": { "title": "Human readable only (humanReadable=\"REPLACE\")", "type": "object", "properties": { "fullName": { "type": "string", "description": "The full name of the Employee (first name + surname)." }, "displayName": { "type": "string", "description": "Employee's display name. This defaults to first name & last name but can be customized." }, "creationDateTime": { "type": "string", "description": "The full timestamp of creation of the Employee." }, "work": { "anyOf": [ { "$ref": "#/components/schemas/WorkPartReadable" } ] }, "avatarUrl": { "type": "string", "description": "The URL of the source of the avatar image." }, "secondName": { "type": "string", "description": "Employee's surname." }, "about": { "anyOf": [ { "$ref": "#/components/schemas/AboutPartReadable" } ] }, "companyId": { "type": "string", "description": "The ID of the employee's company." }, "email": { "type": "string", "description": "Employee's email address.", "format": "email" }, "surname": { "type": "string", "description": "Employee's surname." }, "coverImageUrl": { "type": "string", "description": "The URL of the cover image." }, "id": { "type": "string", "description": "A unique identifier representing a specific employee." }, "firstName": { "type": "string", "description": "Employee's first name." } } }, "EmployeeResponseMachineFormat": { "title": "Machine format only (humanReadable=\"\")", "type": "object", "properties": { "fullName": { "type": "string", "description": "The full name of the Employee (first name + surname)." }, "/work/indirectReports": { "type": "array", "description": "The internal IDs of the people the Employee reports to indirectly.", "items": { "type": "string" } }, "/about/avatar": { "type": "object", "description": "The avatar URL of the employee.", "properties": { "value": { "type": "string" } } }, "/work/reportsTo/email": { "type": "object", "description": "The email of the person the employee reports to.", "properties": { "value": { "type": "string" } } }, "displayName": { "type": "string", "description": "Employee's display name. This defaults to first name & last name but can be customized." }, "/root/firstName": { "type": "object", "description": "The first name of the employee.", "properties": { "value": { "type": "string" } } }, "/work/employeeIdInCompany": { "type": "object", "description": "The internal ID of the employee.", "properties": { "value": { "type": "number" } } }, "/work/tenureDurationYears": { "type": "object", "description": "The tenure duration in exact years of the employee.", "properties": { "value": { "type": "number" } } }, "/about/foodPreferences": { "type": "object", "description": "The food preferences of the employee.", "properties": { "value": { "type": "string" } } }, "/work/site": { "type": "object", "description": "The site name of the employee.", "properties": { "value": { "type": "string" } } }, "/work/tenureYears": { "type": "object", "description": "The tenure duration in years of the employee (rounded value).", "properties": { "value": { "type": "string" } } }, "creationDateTime": { "type": "string", "description": "The full timestamp of creation of the Employee." }, "hobbies": { "type": "object", "properties": { "value": { "type": "array", "description": "An array of the employee's hobbies.", "items": { "type": "string" } } } }, "/root/email": { "type": "object", "description": "The employee's email.", "properties": { "value": { "type": "string" } } }, "/work/title": { "type": "object", "description": "The employee's title.", "properties": { "value": { "type": "string" } } }, "employee": { "type": "object", "properties": { "payrollManager": { "type": "string" }, "hrbp": { "type": "string" }, "itAdmin": { "type": "string" }, "buddy": { "type": "string" } } }, "work": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/WorkPartMachineFormat" } ] }, "avatarUrl": { "type": "string", "description": "The URL of the source of the avatar image." }, "secondName": { "type": "string", "description": "Employee's surname." }, "about": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/AboutPartMachineFormat" } ] }, "/root/fullName": { "type": "object", "description": "The employee's full name.", "properties": { "value": { "type": "string" } } }, "companyId": { "type": "number", "description": "The ID of the employee's company." }, "/root/coverImageUrl": { "type": "object", "description": "The employee's cover image.", "properties": { "value": { "type": "string" } } }, "/work/secondLevelManager": { "type": "object", "description": "The ID of the second level manager of the employee.", "properties": { "value": { "type": "string" } } }, "/work/directReports": { "type": "object", "description": "The number of people the employee reports to directly.", "properties": { "value": { "type": "number" } } }, "/work/yearsOfService": { "type": "object", "description": "The number of years the employee has been in service.", "properties": { "value": { "type": "number" } } }, "/work/daysOfPreviousService": { "type": "object", "description": "The number of years the employee has been in service previously.", "properties": { "value": { "type": "number" } } }, "/about/about": { "type": "object", "description": "Employee's about sentence.", "properties": { "value": { "type": "string" } } }, "/root/avatarUrl": { "type": "object", "description": "The url for the avatar file of the employee.", "properties": { "value": { "type": "string" } } }, "/work/shortStartDate": { "type": "object", "description": "The start date of the employee in a short format (without the year).", "properties": { "value": { "type": "string" } } }, "/work/activeEffectiveDate": { "type": "object", "description": "The date the employee bacame active.", "properties": { "value": { "type": "string" } } }, "/root/id": { "type": "object", "description": "The ID of the employee.", "properties": { "value": { "type": "string" } } }, "email": { "type": "string", "description": "Employee's email address.", "format": "email" }, "/work/manager": { "type": "object", "description": "The ID of the employee's manager.", "properties": { "value": { "type": "string" } } }, "surname": { "type": "string", "description": "Employee's surname." }, "/work/reportsTo": { "type": "object", "description": "The details of the person the employee reports to.", "properties": { "value": { "type": "object", "properties": { "displayName": { "type": "string" }, "email": { "type": "string" }, "surname": { "type": "string" }, "firstName": { "type": "string" }, "id": { "type": "string" } } } } }, "/root/companyId": { "type": "object", "description": "The ID of the employee's company.", "properties": { "value": { "type": "number" } } }, "/root/displayName": { "type": "object", "description": "The display name of the employee.", "properties": { "value": { "type": "string" } } }, "/work/department": { "type": "object", "description": "The department of the employee.", "properties": { "value": { "type": "string" } } }, "/work/isManager": { "type": "object", "description": "The department of the employee.", "properties": { "value": { "type": "boolean" } } }, "/work/originalStartDate": { "type": "object", "description": "The original date the employee started work.", "properties": { "value": { "type": "string" } } }, "coverImageUrl": { "type": "string", "description": "The URL of the cover image." }, "/work/reportsToIdInCompany": { "type": "object", "description": "The ID of the person this employee reports to.", "properties": { "value": { "type": "number" } } }, "/work/tenureDuration": { "type": "object", "description": "The tenture duration of the employee.", "properties": { "value": { "type": "object", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } } } }, "/about/superpowers": { "type": "object", "description": "The super powers of the employee.", "properties": { "value": { "type": "array", "items": { "type": "string" } } } }, "id": { "type": "string", "description": "A unique identifier representing a specific employee." }, "firstName": { "type": "string", "description": "Employee's first name." }, "/work/siteId": { "type": "object", "description": "The site ID of the employee's site.", "properties": { "value": { "type": "number" } } }, "/work/durationOfEmployment": { "type": "object", "description": "The duration of the employee's employment.", "properties": { "value": { "type": "object", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } } } } } }, "Employees": { "type": "object", "description": "Employee read response for Search for employees. Contains all matching employees for the request in one employees array (not split across pages). Machine-format field values use slash-notation keys (e.g. /root/id) with a value property. The same employee object may also include nested category objects (e.g. work.siteId). Request field IDs use dot notation from metadata (e.g. root.id). See People read API contract.", "properties": { "employees": { "type": "array", "description": "All employees matching the search request and service user scope for this call.", "items": { "oneOf": [ { "$ref": "#/components/schemas/EmployeeResponseReadable" }, { "$ref": "#/components/schemas/EmployeeResponseMachineFormat" } ] } } } }, "EmployeesPayrollData": { "type": "object", "properties": { "employees": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/EmployeeResponseReadable" }, { "type": "object", "properties": { "payroll": { "type": "object", "properties": { "employmentType": { "allOf": [ { "$ref": "#/components/schemas/EmploymentEntry" } ] } } } } }, { "type": "object", "properties": { "about": { "$ref": "#/components/schemas/AboutPartMachineFormat" } } } ] } } } }, "EmployeeProfile": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier representing a specific employee." }, "firstName": { "type": "string", "description": "Employee's first name." }, "surname": { "type": "string", "description": "Employee's surname." }, "email": { "type": "string", "description": "Employee's email address.", "format": "email" }, "displayName": { "type": "string", "description": "The employee's display name. This defaults to first name & last name but can be customized." }, "personal": { "$ref": "#/components/schemas/PersonalPart" }, "about": { "$ref": "#/components/schemas/AboutPart" }, "work": { "$ref": "#/components/schemas/WorkPartMachineFormat" } } }, "EmployeesProfiles": { "type": "object", "properties": { "employees": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeProfile" } } } }, "Fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "Field": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the field." }, "categoryId": { "type": "string", "description": "ID of the field category." }, "categoryDisplayName": { "type": "string", "description": "Display name of the field category." }, "category": { "type": "string", "description": "To be deprecated. Use categoryId instead." }, "name": { "type": "string", "description": "Name of the field." }, "description": { "type": "string", "description": "Description of the field." }, "jsonPath": { "type": "string", "description": "A dot-separated path of this field value in the employee JSON returned by the /v1/profiles endpoint." }, "type": { "type": "string", "description": "The type of the field. Supported field types: text, text-area, number, date, list, multi-list, hierarchy-list, currency, employee-reference, document." }, "typeData": { "type": "object", "properties": { "listId": { "type": "string", "description": "The ID of the list in the /v1/company/named-lists endpoint." } } }, "historical": { "type": "boolean", "description": "When true, this field keeps the history of its values, each being active starting from a certain date. The default value is false." } } }, "CreateFieldRequest": { "required": [ "category", "name", "type" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the field." }, "category": { "type": "string", "description": "The category of the field." }, "type": { "type": "string", "description": "The type of field. Supported field types: text, text-area, number, date, list, multi-list, hierarchy-list, currency, employee-reference, document." }, "description": { "type": "string", "description": "The description of the field." }, "historical": { "type": "boolean", "default": false, "description": "When true, this field keeps the history of its values, each being active starting from a certain date. The default value is false." } } }, "UpdateFieldRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the field." }, "description": { "type": "string", "description": "The description of the field." } } }, "Lists": { "type": "array", "items": { "$ref": "#/components/schemas/List" } }, "List": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the list" }, "items": { "type": "array", "description": "The elements in the list.", "items": { "$ref": "#/components/schemas/ListItem" } } } }, "FlatListItemId": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the list item." } } }, "FieldId": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the field." } } }, "NestedListItem": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "type": "string" }, "name": { "type": "string" }, "archived": { "type": "boolean" }, "children": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "value": { "type": "string" }, "name": { "type": "string" }, "archived": { "type": "boolean" } } } } } }, "ListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal ID of the item." }, "value": { "type": "string", "description": "Value of the item." }, "name": { "type": "string", "description": "Name of the item." }, "archived": { "type": "boolean", "description": "Whether the item is archived (not available for selection)." }, "children": { "type": "array", "description": "Nested items - if the list is nested.", "items": { "oneOf": [ { "$ref": "#/components/schemas/NestedListItem" } ] } } } }, "NewListItem": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "Name of the item." }, "parentId": { "type": "integer", "description": "ID of the new hierarchy parent node." } } }, "UpdateListItemRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the item." }, "parentId": { "type": "integer", "description": "ID of the new hierarchy parent node." } } }, "OnboardingWizards": { "type": "object", "properties": { "wizards": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingWizard" } } } }, "OnboardingWizard": { "type": "object", "properties": { "id": { "type": "number", "format": "long" }, "name": { "type": "string" } } }, "InvitationByWizard": { "required": [ "welcomeWizardId" ], "type": "object", "properties": { "welcomeWizardId": { "type": "integer", "description": "The Welcome wizard ID." } } }, "UploadAvatar": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the source of the avatar image." } } }, "StartDateUpdate": { "required": [ "startDate" ], "type": "object", "properties": { "startDate": { "type": "string", "description": "The date this entry becomes effective.", "format": "date" }, "reason": { "type": "string", "description": "Additional info for the start date update." } } }, "ChangeEmail": { "type": "object", "properties": { "email": { "type": "string", "description": "new email" } } }, "Error": { "type": "object", "properties": { "key": { "type": "string", "description": "The unique identifier of the error." }, "error": { "type": "string", "description": "A human readable error message." } } }, "CustomTableColumn": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the column" }, "name": { "type": "string", "description": "The name of the column" }, "description": { "type": "string", "description": "The description of the column" }, "mandatory": { "type": "boolean", "description": "Flag which means that column must be present during creation and its value can't be null during update" }, "type": { "type": "string", "description": "The type of the column. Supported column types: text, text-area, number, date, list, multi-list, hierarchy-list, currency, employee-reference, document." }, "typeData": { "type": "object", "properties": { "listId": { "type": "string", "description": "The ID of the list in the /v1/company/named-lists endpoint." } } } } }, "CustomTableMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier of custom table" }, "category": { "type": "string", "description": "The ID of the category to which the custom table belongs" }, "name": { "type": "string", "description": "The name of custom table" }, "description": { "type": "string", "description": "The description of custom table" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTableColumn" } } } }, "CustomTableMetadataList": { "type": "object", "properties": { "tables": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTableMetadata" } } } }, "CustomTableCreateEntriesList": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTableCreateEntry" } } } }, "CustomTableCreateEntry": { "type": "object", "description": "Object with column IDs as keys and their values", "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "string" } ] } }, "CustomTableEntriesList": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/CustomTableEntry" } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "CustomTableEntry": { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the row" }, "changedBy": { "type": "string", "description": "The backend ID of the user that changed the value" } }, "description": "The row data depends on what is defined in the table's schema, use HiBob Custom Table Metadata API to get list of defined columns. The only property that's always present is ID and ChangeBy.", "example": { "id": 1021262, "changedBy": 3332883804594372000, "column_1663598152485": 5185395, "column_1663598024920": "2022-09-30", "column_1663598120787": "2871255975417872769", "column_1663598037763": 123456, "column_1663598145154": 371223, "column_1663597977169": "text text", "column_1663597992534": "text area text area text area", "column_1663598108167": { "value": 240, "currency": "USD" }, "column_1663598062584": "252614471", "column_1663598090762": [ "252614475", "252614476" ], "humanReadable": { "column_1663597992534": "text area text area text area", "column_1663598090762": "B,A", "column_1663598108167": "$240.00", "column_1663598145154": "B \\ 3", "column_1663598062584": "C", "column_1663598152485": "5185395", "column_1663597977169": "text text", "column_1663598037763": "123456", "column_1663598024920": "30/09/2022", "column_1663598120787": "Austin Legge" } } }, "BulkWorkTableResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "values": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/WorkEntries" } ] } } } } }, "response_metadata": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page." } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "object", "properties": { "error": { "type": "string", "example": "MISSING_PERMISSION" }, "message": { "type": "string", "example": "You don't have permission to access data for employees with ids: 2578509511618723822" } } } } } } } }, "BulkSalariesTableResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "values": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/SalaryEntries" } ] } } } } }, "response_metadata": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page." } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "object", "properties": { "error": { "type": "string", "example": "MISSING_PERMISSION" }, "message": { "type": "string", "example": "You don't have permission to access data for employees with ids: 2578509511618723822" } } } } } } } }, "BulkEmploymentTableResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "values": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/EmploymentEntries" } ] } } } } }, "response_metadata": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page." } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "object", "properties": { "error": { "type": "string", "example": "MISSING_PERMISSION" }, "message": { "type": "string", "example": "You don't have permission to access data for employees with ids: 2578509511618723822" } } } } } } } }, "BulkDependentsTableResponse": { "type": "object", "description": "Cursor-paginated bulk response for dependents table entries.", "properties": { "results": { "type": "array", "description": "Dependents table entries grouped by employee.", "items": { "type": "object", "description": "One employee's dependents entries on this page.", "properties": { "employeeId": { "type": "string", "description": "Employee ID these dependent entries belong to." }, "values": { "type": "array", "description": "Dependent entries for this employee on the current page.", "items": { "$ref": "#/components/schemas/DependentEntry" } } } } }, "response_metadata": { "type": "object", "description": "Pagination metadata for the bulk response.", "properties": { "next_cursor": { "type": "string", "description": "Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page." } } }, "errors": { "type": "array", "description": "Permission errors for employees that were requested but could not be read. In the live JSON payload this is an object keyed by employee ID (`{ \"\": { \"error\", \"message\" } }`); documented as an array of entries (same pattern as other bulk employee-table responses) so the schema stays strict without `additionalProperties`.", "items": { "type": "object", "description": "Permission error for one employee.", "properties": { "employeeId": { "type": "string", "description": "Employee ID that could not be accessed." }, "error": { "type": "string", "description": "Machine-readable error code.", "example": "MISSING_PERMISSION" }, "message": { "type": "string", "description": "Human-readable explanation of the permission error.", "example": "You don't have permission to access data for employee with id other-employee" } } } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "BulkRightToWorkTableResponse": { "type": "object", "description": "Cursor-paginated bulk response for right to work table entries.", "properties": { "results": { "type": "array", "description": "Right to work table entries grouped by employee.", "items": { "type": "object", "description": "One employee's right to work entries on this page.", "properties": { "employeeId": { "type": "string", "description": "Employee ID these right to work entries belong to." }, "values": { "type": "array", "description": "Right to work entries for this employee on the current page.", "items": { "$ref": "#/components/schemas/RightToWorkEntry" } } } } }, "response_metadata": { "type": "object", "description": "Pagination metadata for the bulk response.", "properties": { "next_cursor": { "type": "string", "description": "Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page." } } }, "errors": { "type": "array", "description": "Permission errors for employees that were requested but could not be read. In the live JSON payload this is an object keyed by employee ID (`{ \"\": { \"error\", \"message\" } }`); documented as an array of entries (same pattern as other bulk employee-table responses) so the schema stays strict without `additionalProperties`.", "items": { "type": "object", "description": "Permission error for one employee.", "properties": { "employeeId": { "type": "string", "description": "Employee ID that could not be accessed." }, "error": { "type": "string", "description": "Machine-readable error code.", "example": "MISSING_PERMISSION" }, "message": { "type": "string", "description": "Human-readable explanation of the permission error.", "example": "You don't have permission to access data for employee with id other-employee" } } } }, "restricted_columns": { "$ref": "#/components/schemas/RestrictedColumnsMetadata" } } }, "BulkLifecycleTableResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "string" }, "values": { "type": "array", "items": { "type": "string", "anyOf": [ { "$ref": "#/components/schemas/LifeCycleEntries" } ] } } } } }, "response_metadata": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Contains a string value if there is a 'next' page of data. `null` if there is no more data. Use this value as the `cursor` parameter for pagination to get the next page." } } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "employeeId": { "type": "object", "properties": { "error": { "type": "string", "example": "MISSING_PERMISSION" }, "message": { "type": "string", "example": "You don't have permission to access data for employees with ids: 2578509511618723822" } } } } } } } }, "RestrictedColumnsMetadata": { "type": "object", "description": "Indicates which columns were filtered from the response due to field-level permissions (FLP). This object is only present when FLP is enabled for the company and the service user has partial column permissions. To learn more, see Field level permissions.", "properties": { "no_view_permission": { "type": "array", "items": { "type": "string" }, "description": "Columns filtered because the service user lacks View permission for these fields." }, "no_view_history_permission": { "type": "array", "items": { "type": "string" }, "description": "Columns filtered because the service user lacks View History permission. Only present for historical tables (work, employment, salaries, lifecycle)." } } } }, "securitySchemes": { "Basic": { "type": "http", "scheme": "basic", "description": "Basic HTTP authentication using service user credentials" }, "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "OAuth 2.0", "description": "OAuth 2.0 authentication using an Access Token is available for registered partners only. Try It! does not support the full HiBob OAuth flow. You can follow these steps to complete the OAuth 2.0 flow in Postman and then paste the token here." } } } } ```