Employees
This endpoint manages employee records within the organization.
Overview
The Employees API provides comprehensive functionality for managing employee data, including personal information, organizational structure, employment details, and team assignments. It serves as the central repository for employee-related information used throughout the Pulse platform.
Key Features
- Employee Profiles: Create and manage detailed employee records
- Organizational Structure: Track reporting relationships and team memberships
- Employment Details: Manage employment types, service numbers, and status
- Integration: Synchronizes with IAM service for core identity information
Data Synchronization
This endpoint duplicates certain fields from the IAM People service to maintain data consistency across services. The synchronized fields include personal information (names) and organizational assignments.
Common Use Cases
- HR management of employee records
- Organization chart generation
- Team management and planning
- Leave and absence management (via related services)
Endpoints
- get /api/v3/office/employees
- post /api/v3/office/employees
- get /api/v3/office/employees/:resource_id
- patch /api/v3/office/employees/:resource_id
- get /api/v3/office/employees/availability
get/api/v3/office/employees
Return a paginated list of office/employees
Input Schema
object
page?:
object
The page number, default to 1
number?: integer
The number of items per page, default to 1000
size?: integer
The sort order, comma separated list of fields. See sorting section for more details
sort?: string
Set to true to return the total number of items in the collection
count?: boolean
filter?:
object
id?: unknown
first_name?: unknown
middle_name?: unknown
last_name?: unknown
email?: unknown
picture_url?: unknown
service_number?: unknown
employment_type?: unknown
hired_at?: unknown
terminated_at?: unknown
terminated_temporary?: unknown
created_at?: unknown
teams?: unknown
is_manager?: unknown
is_hr?: unknown
position?: unknown
manager_id?: unknown
manager_ids?: unknown
planning_id?: unknown
organizational_unit?: unknown
emergency_name?: unknown
emergency_relationship?: unknown
emergency_phone?: unknown
starting_date?: unknown
end_of_probation_date?: unknown
department?: unknown
job_classification?: unknown
job_level?: unknown
job_sub_level?: unknown
pregnancy_due_date?: unknown
facets?: unknown
id?: unknown
id__in?: unknown
id__neq?: unknown
service_number__match?: unknown
organizational_unit__match?: unknown
teams__contains?: unknown
teams_of_employee_id?: unknown
position__match?: unknown
manager_ids__contains?: unknown
employment_type__in?: unknown
planning_id?: unknown
planning_id__in?: unknown
active?: unknown
hired_at__gte?: unknown
hired_at__lte?: unknown
created_at__gte?: unknown
created_at__lte?: unknown
status?: unknown
search?: unknown
all_managers_of?: unknown
all_subordinates_of?: unknown
include_managers?: unknown
ous_prefix?: unknown
The related resources to include in the response. Allowed resources are:
- `planning`
- `leave_budget`
included?: - `planning`
- `leave_budget`
array
Elements: string
The fields to include in the response.
The key is the resource type and the value is an array of fields.
fields?: The key is the resource type and the value is an array of fields.
dictionary
Values: array
Typescript
type InputSchema = {
page?: {
// The page number, default to 1
number?: number;
// The number of items per page, default to 1000
size?: number;
};
// The sort order, comma separated list of fields. See sorting section for more details
sort?: string;
// Set to true to return the total number of items in the collection
count?: boolean;
filter?: {
id?: any;
first_name?: any;
middle_name?: any;
last_name?: any;
email?: any;
picture_url?: any;
service_number?: any;
employment_type?: any;
hired_at?: any;
terminated_at?: any;
terminated_temporary?: any;
created_at?: any;
teams?: any;
is_manager?: any;
is_hr?: any;
position?: any;
manager_id?: any;
manager_ids?: any;
planning_id?: any;
organizational_unit?: any;
emergency_name?: any;
emergency_relationship?: any;
emergency_phone?: any;
starting_date?: any;
end_of_probation_date?: any;
department?: any;
job_classification?: any;
job_level?: any;
job_sub_level?: any;
pregnancy_due_date?: any;
facets?: any;
id?: any;
id__in?: any;
id__neq?: any;
service_number__match?: any;
organizational_unit__match?: any;
teams__contains?: any;
teams_of_employee_id?: any;
position__match?: any;
manager_ids__contains?: any;
employment_type__in?: any;
planning_id?: any;
planning_id__in?: any;
active?: any;
hired_at__gte?: any;
hired_at__lte?: any;
created_at__gte?: any;
created_at__lte?: any;
status?: any;
search?: any;
all_managers_of?: any;
all_subordinates_of?: any;
include_managers?: any;
ous_prefix?: any;
};
// The related resources to include in the response. Allowed resources are:
// - `planning`
// - `leave_budget`
included?: Array<string>;
// The fields to include in the response.
// The key is the resource type and the value is an array of fields.
fields?: { [key: string]: Array<any> };
};
Output Schema
object
data:
array
Elements:
object
type: string
id?: string
attributes?:
object
id?: integer
first_name?: string
middle_name?: string
last_name?: string
email?: string
picture_url?: string or null
service_number?: string
employment_type?: string
hired_at?: date
terminated_at?: date or null
terminated_temporary?: boolean or null
created_at?: datetime
teams?: array
is_manager?: boolean
is_hr?: boolean
position?: string
manager_ids?: array
organizational_unit?: string
emergency_name?: string
emergency_relationship?: string
emergency_phone?: string
starting_date?: date
end_of_probation_date?: date or null
department?: string or null
job_classification?: string or null
job_level?: string or null
job_sub_level?: string or null
pregnancy_due_date?: date or null
facets?: array
relationships?: open struct
included?:
array
Elements: open struct
Typescript
type OutputSchema = {
data: Array<{
type: string;
id?: string;
attributes?: {
id?: number;
first_name?: string;
middle_name?: string;
last_name?: string;
email?: string;
picture_url?: string | null;
service_number?: string;
employment_type?: string;
hired_at?: Date;
terminated_at?: Date | null;
terminated_temporary?: boolean | null;
created_at?: Date;
teams?: Array<any>;
is_manager?: boolean;
is_hr?: boolean;
position?: string;
manager_ids?: Array<any>;
organizational_unit?: string;
emergency_name?: string;
emergency_relationship?: string;
emergency_phone?: string;
starting_date?: Date;
end_of_probation_date?: Date | null;
department?: string | null;
job_classification?: string | null;
job_level?: string | null;
job_sub_level?: string | null;
pregnancy_due_date?: Date | null;
facets?: Array<any>;
};
relationships?: Record<string, any>;
}>;
included?: Array<Record<string, any>>;
};
post/api/v3/office/employees
Create a new office/employees
Input Schema
object
data:
object
type: string
attributes:
object
id?: integer
first_name?: string
middle_name?: string
last_name?: string
email?: string
picture_url?: string or null
service_number?: string
employment_type?: string
hired_at?: date
terminated_at?: date or null
terminated_temporary?: boolean or null
created_at?: datetime
teams?: array
is_manager?: boolean
is_hr?: boolean
position?: string
manager_ids?: array
organizational_unit?: string
emergency_name?: string
emergency_relationship?: string
emergency_phone?: string
starting_date?: date
end_of_probation_date?: date or null
department?: string or null
job_classification?: string or null
job_level?: string or null
job_sub_level?: string or null
pregnancy_due_date?: date or null
facets?: array
relationships?:
object
planning:
object
data:
object
type: string
id?: string
Typescript
type InputSchema = {
data: {
type: string;
attributes: {
id?: number;
first_name?: string;
middle_name?: string;
last_name?: string;
email?: string;
picture_url?: string | null;
service_number?: string;
employment_type?: string;
hired_at?: Date;
terminated_at?: Date | null;
terminated_temporary?: boolean | null;
created_at?: Date;
teams?: Array<any>;
is_manager?: boolean;
is_hr?: boolean;
position?: string;
manager_ids?: Array<any>;
organizational_unit?: string;
emergency_name?: string;
emergency_relationship?: string;
emergency_phone?: string;
starting_date?: Date;
end_of_probation_date?: Date | null;
department?: string | null;
job_classification?: string | null;
job_level?: string | null;
job_sub_level?: string | null;
pregnancy_due_date?: Date | null;
facets?: Array<any>;
};
relationships?: { planning: { data: { type: string; id?: string } } };
};
};
get/api/v3/office/employees/:resource_id
Show a specific office/employees
Input Schema
object
resource_id: integer
included?:
array
Elements: string
fields?:
dictionary
Values: array
Typescript
type InputSchema = {
resource_id: number;
included?: Array<string>;
fields?: { [key: string]: Array<any> };
};
Output Schema
object
data:
object
type: string
id?: string
attributes?:
object
id?: integer
first_name?: string
middle_name?: string
last_name?: string
email?: string
picture_url?: string or null
service_number?: string
employment_type?: string
hired_at?: date
terminated_at?: date or null
terminated_temporary?: boolean or null
created_at?: datetime
teams?: array
is_manager?: boolean
is_hr?: boolean
position?: string
manager_ids?: array
organizational_unit?: string
emergency_name?: string
emergency_relationship?: string
emergency_phone?: string
starting_date?: date
end_of_probation_date?: date or null
department?: string or null
job_classification?: string or null
job_level?: string or null
job_sub_level?: string or null
pregnancy_due_date?: date or null
facets?: array
relationships?: open struct
included?:
array
Elements: open struct
Typescript
type OutputSchema = {
data: {
type: string;
id?: string;
attributes?: {
id?: number;
first_name?: string;
middle_name?: string;
last_name?: string;
email?: string;
picture_url?: string | null;
service_number?: string;
employment_type?: string;
hired_at?: Date;
terminated_at?: Date | null;
terminated_temporary?: boolean | null;
created_at?: Date;
teams?: Array<any>;
is_manager?: boolean;
is_hr?: boolean;
position?: string;
manager_ids?: Array<any>;
organizational_unit?: string;
emergency_name?: string;
emergency_relationship?: string;
emergency_phone?: string;
starting_date?: Date;
end_of_probation_date?: Date | null;
department?: string | null;
job_classification?: string | null;
job_level?: string | null;
job_sub_level?: string | null;
pregnancy_due_date?: Date | null;
facets?: Array<any>;
};
relationships?: Record<string, any>;
};
included?: Array<Record<string, any>>;
};
patch/api/v3/office/employees/:resource_id
Update a office/employees
Input Schema
object
resource_id: integer
data:
object
type: string
attributes:
object
id?: integer
first_name?: string
middle_name?: string
last_name?: string
email?: string
picture_url?: string or null
service_number?: string
employment_type?: string
hired_at?: date
terminated_at?: date or null
terminated_temporary?: boolean or null
created_at?: datetime
teams?: array
is_manager?: boolean
is_hr?: boolean
position?: string
manager_ids?: array
organizational_unit?: string
emergency_name?: string
emergency_relationship?: string
emergency_phone?: string
starting_date?: date
end_of_probation_date?: date or null
department?: string or null
job_classification?: string or null
job_level?: string or null
job_sub_level?: string or null
pregnancy_due_date?: date or null
facets?: array
relationships?:
object
planning:
object
data:
object
type: string
id?: string
Typescript
type InputSchema = {
resource_id: number;
data: {
type: string;
attributes: {
id?: number;
first_name?: string;
middle_name?: string;
last_name?: string;
email?: string;
picture_url?: string | null;
service_number?: string;
employment_type?: string;
hired_at?: Date;
terminated_at?: Date | null;
terminated_temporary?: boolean | null;
created_at?: Date;
teams?: Array<any>;
is_manager?: boolean;
is_hr?: boolean;
position?: string;
manager_ids?: Array<any>;
organizational_unit?: string;
emergency_name?: string;
emergency_relationship?: string;
emergency_phone?: string;
starting_date?: Date;
end_of_probation_date?: Date | null;
department?: string | null;
job_classification?: string | null;
job_level?: string | null;
job_sub_level?: string | null;
pregnancy_due_date?: Date | null;
facets?: Array<any>;
};
relationships?: { planning: { data: { type: string; id?: string } } };
};
};
get/api/v3/office/employees/availability
Get employee availability for a date range.
This endpoint returns the availability status of employees for each day in the specified date range. It takes into account employee schedules, holidays, and approved leave requests.
The date range is limited to a maximum of 90 days.
Response Format
The response includes an array of availability records with the following information:
-
employee_id: The ID of the employee -
date: The date for which availability is reported -
scheduled: Whether the employee is scheduled to work on this date -
available: Whether the employee is actually available (not on leave or holiday)
Common Use Cases
- Checking team availability for project planning
- Scheduling meetings or assignments based on employee availability
- Generating availability reports for management
Input Schema
object
filter:
object
from: date
to: date
employee_ids?: array
Typescript
type InputSchema = {
filter: { from: Date; to: Date; employee_ids?: Array<any> };
};
Output Schema
object
data:
array
Elements:
object
employee_id: integer
date: date
scheduled: boolean
available: boolean
Typescript
type OutputSchema = {
data: Array<{
employee_id: number;
date: Date;
scheduled: boolean;
available: boolean;
}>;
};