> ## Documentation Index > Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get Employees > Returns a list of Employee objects. ## OpenAPI ````yaml get /api/hris/v1/employees openapi: 3.1.0 info: title: Bindbee APIs version: 0.1.0 servers: - url: https://api.bindbee.dev - url: https://api-eu.bindbee.dev security: [] paths: /api/hris/v1/employees: get: tags: - Employee summary: Get Employees description: Returns a list of Employee objects. operationId: get_employees_api_hris_v1_employees_get parameters: - name: ids in: query required: false schema: anyOf: - type: string - type: 'null' description: The ID of employees to fetch examples: - >- 01931edf-04b6-7391-8a5c-93ac4b395316,01931edf-04c8-7649-a470-d85f6161bd1a title: Ids description: The ID of employees to fetch - name: manager_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The ID of managers to fetch employees for examples: - >- 01931edf-04b6-7391-8a5c-93ac4b395316,01931edf-04c8-7649-a470-d85f6161bd1a title: Manager Id description: The ID of managers to fetch employees for - name: remote_id in: query required: false schema: type: string description: The third-party API ID of the matching object. examples: - '3235005483341316245' title: Remote Id description: The third-party API ID of the matching object. - name: company_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The ID of companies to fetch employees for examples: - >- 01931edf-04b6-7391-8a5c-93ac4b395316,01931edf-04c8-7649-a470-d85f6161bd1a title: Company Id description: The ID of companies to fetch employees for - name: include_raw_data in: query required: false schema: type: boolean description: >- Whether to include the original data Bindbee fetched from the third-party to produce these models. examples: - false default: false title: Include Raw Data description: >- Whether to include the original data Bindbee fetched from the third-party to produce these models. - name: include_custom_fields in: query required: false schema: type: boolean description: Whether to include custom fields in the response. examples: - false default: false title: Include Custom Fields description: Whether to include custom fields in the response. - name: employment_status in: query required: false schema: $ref: '#/components/schemas/HRISEmploymentStatus' description: >- If provided, will only return employees with this employment status. examples: - ACTIVE description: If provided, will only return employees with this employment status. - name: employee_number in: query required: false schema: type: string description: If provided, will only return employees for this employee number examples: - '000000168' title: Employee Number description: If provided, will only return employees for this employee number - name: groups in: query required: false schema: anyOf: - type: string - type: 'null' description: The ID of groups to fetch employees for examples: - >- 01931edf-04b6-7391-8a5c-93ac4b395316,01931edf-04c8-7649-a470-d85f6161bd1a title: Groups description: The ID of groups to fetch employees for - name: pay_group_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The ID of pay groups to fetch employees for examples: - >- 01931edf-04b6-7391-8a5c-93ac4b395316,01931edf-04c8-7649-a470-d85f6161bd1a title: Pay Group Id description: The ID of pay groups to fetch employees for - name: page_size in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Number of results to return per page. Maximum size is 200. default: 50 title: Page Size description: Number of results to return per page. Maximum size is 200. - name: cursor in: query required: false schema: type: string description: The pagination cursor value. title: Cursor description: The pagination cursor value. - name: modified_after in: query required: false schema: type: string description: >- If provided, only objects synced by Bindbee after this date time will be returned. Format: DateTime (ISO 8601) examples: - '2024-02-21T21:22:12.993Z' title: Modified After description: >- If provided, only objects synced by Bindbee after this date time will be returned. Format: DateTime (ISO 8601) - name: expand in: query required: false schema: type: string description: >- Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. You can also specify required fields in [] for each relation name. examples: - manager[first_name,last_name] title: Expand description: >- Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. You can also specify required fields in [] for each relation name. - name: x-connector-token in: header required: true schema: type: string title: X-Connector-Token responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginatedResponse_HrisEmployeeResponse_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: HRISEmploymentStatus: type: string enum: - ACTIVE - PENDING - INACTIVE - ACTIVE_EXTERNAL - INACTIVE_EXTERNAL - '-' - LEAVE - DECEASED - RETIRED title: HRISEmploymentStatus PaginatedResponse_HrisEmployeeResponse_: properties: cursor: anyOf: - type: string - type: 'null' title: Cursor description: Cursor value to fetch next set of items examples: - MDE4YjE4ZWYtYzk5Yy03YTg2LTk5NDYtN2I3YzlkNTQzM2U1 page_size: type: integer title: Page Size description: Indicates the count of items in the response examples: - 50 items: items: $ref: '#/components/schemas/HrisEmployeeResponse' type: array title: Items description: List of items in the current response examples: - {} type: object required: - cursor - page_size - items title: PaginatedResponse[HrisEmployeeResponse] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError HrisEmployeeResponse: properties: id: type: string format: uuid title: Id examples: - 018b18ef-c487-703c-afd9-0ca478ccd9d6 remote_id: anyOf: - type: string - type: 'null' title: Remote Id description: The third-party API ID of the matching object. examples: - '123321' modified_at: type: string title: Modified At description: This is the datetime that this object was last updated by Bindbee examples: - '2021-10-16T00:00:00Z' raw_data: anyOf: - additionalProperties: true type: object - type: 'null' title: Raw Data description: This is the Raw data examples: - key_1: Platform dependent data 1 key_2: Platform dependent data 2 custom_fields: anyOf: - additionalProperties: true type: object - type: 'null' title: Custom Fields description: The custom fields related to the model examples: - category_group: REG disability_type: ASBERG hire_date: '1991-03-16T00:00:00' hire_source: REFER nationality: USA original_hire_date: '1991-03-16T00:00:00' employee_number: anyOf: - type: string - type: 'null' title: Employee Number description: >- The employee's number that appears in the third-party integration's UI. examples: - '1' company: anyOf: - {} - type: 'null' title: Company description: The ID of the employee's company. examples: - 018af1fe-1250-772d-87c5-6f725a579e8a first_name: anyOf: - type: string - type: 'null' title: First Name description: The employee's first name. examples: - Kunal middle_name: anyOf: - type: string - type: 'null' title: Middle Name description: The employee's middle name. examples: - Christopher last_name: anyOf: - type: string - type: 'null' title: Last Name description: The employee's last name. examples: - Tyagi preferred_name: anyOf: - type: string - type: 'null' title: Preferred Name description: The employee's preferred first name. examples: - Dark Knight display_full_name: anyOf: - type: string - type: 'null' title: Display Full Name description: >- The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name. examples: - Kunal Tyagi username: anyOf: - type: string - type: 'null' title: Username description: The employee's username that appears in the remote UI. examples: - kunaltyagi designation: anyOf: - type: string - type: 'null' title: Designation description: The employee's current designation/title examples: - Chief Technology Officer groups: anyOf: - items: {} type: array - type: 'null' title: Groups description: The IDs of the groups that the employee belongs to. examples: - - 018af1fe-1250-772d-87c5-6f725a579e8a - 018af1fe-1250-772d-87c5-6f725a579e8b department: anyOf: - type: string - type: 'null' title: Department description: The employee's department examples: - Engineering division: anyOf: - type: string - type: 'null' title: Division description: The employee's division examples: - Bangalore Division work_email: anyOf: - type: string - type: 'null' title: Work Email description: The employee's work email. examples: - kunal@bindbee.dev personal_email: anyOf: - type: string - type: 'null' title: Personal Email description: The employee's personal email. examples: - kunaltyagi77@gmail.com mobile_phone_number: anyOf: - type: string - type: 'null' title: Mobile Phone Number description: The employee's mobile phone number. examples: - '+1234567890' home_phone_number: anyOf: - type: string - type: 'null' title: Home Phone Number description: The employee's home phone number. examples: - '+1234567890' country_code: anyOf: - type: string - type: 'null' title: Country Code description: The employee's country code examples: - '+91' home_location: anyOf: - $ref: '#/components/schemas/HrisAddress' - type: 'null' description: The employee's home address. examples: - city: London country: UK location: UK-HO-London name: UK-HO-London postal_code: '56273' state: LND street_1: '1011' street_2: Lane number 4, Golden Villa work_location: anyOf: - $ref: '#/components/schemas/HrisAddress' - type: 'null' description: The employee's work address. examples: - city: London country: UK location: UK-HO-London name: UK-HO-London postal_code: '56273' state: LND street_1: '1011' street_2: Lane number 4, Golden Villa manager: anyOf: - {} - type: 'null' title: Manager description: The employee ID of the employee's manager. examples: - 018aeaff-cc7c-7837-988a-965762bd63c1 pay_group: anyOf: - {} - type: 'null' title: Pay Group description: The employee's pay group examples: - 018af1fe-1250-77c5-9fcd-4bca1e4568f4 ssn: anyOf: - type: string - type: 'null' title: Ssn description: The employee's social security number. examples: - '1234567890' gender: anyOf: - type: string - type: 'null' enum: - MALE - FEMALE - NON-BINARY - OTHER - PREFER_NOT_TO_DISCLOSE - '-' title: Gender description: >- The employee's gender. If the value is not one of the defined enum values, the original value passed through will be returned. examples: - MALE ethnicity: anyOf: - type: string - type: 'null' enum: - AMERICAN_INDIAN_OR_ALASKA_NATIVE - ASIAN_OR_INDIAN_SUBCONTINENT - BLACK_OR_AFRICAN_AMERICAN - HISPANIC_OR_LATINO - NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLANDER - TWO_OR_MORE_RACES - WHITE - PREFER_NOT_TO_DISCLOSE - OTHER - '-' title: Ethnicity description: >- The employee's ethnicity. If the value is not one of the defined enum values, the original value passed through will be returned. examples: - ASIAN_OR_INDIAN_SUBCONTINENT marital_status: anyOf: - type: string - type: 'null' enum: - SINGLE - MARRIED - DIVORCED - SEPARATED - COMMON_LAW - DOMESTIC_PARTNERSHIP - WIDOWED - HEAD_OF_HOUSEHOLD - QUALIFYING_WIDOW_OR_WIDOWER_WITH_DEPENDENT_CHILD - IN_A_RELATIONSHIP - CIVIL_PARTNERSHIP - OTHER - '-' title: Marital Status description: >- The employee's filing status as related to marital status. If the value is not one of the defined enum values, the original value passed through will be returned. examples: - SINGLE tobacco_use: anyOf: - type: boolean - type: 'null' title: Tobacco Use description: Indicates whether the employee uses tobacco or is a smoker. examples: - true date_of_birth: anyOf: - type: string - type: 'null' title: Date Of Birth description: The employee's date of birth. examples: - '1986-10-27T00:00:00Z' start_date: anyOf: - type: string - type: 'null' title: Start Date description: >- The date that the employee started working. If an employee was rehired, the most recent start date will be returned. examples: - '2023-03-05T00:00:00Z' remote_created_at: anyOf: - type: string - type: 'null' title: Remote Created At description: When the third party's employee was created. examples: - '2023-03-01T00:00:00Z' employment_status: anyOf: - type: string - type: 'null' enum: - ACTIVE - PENDING - INACTIVE - ACTIVE_EXTERNAL - INACTIVE_EXTERNAL - '-' - LEAVE - DECEASED - RETIRED title: Employment Status description: >- The employment status of the employee. If the value is not one of the defined enum values, the original value passed through will be returned. examples: - INACTIVE termination_date: anyOf: - type: string - type: 'null' title: Termination Date description: The employee's termination date. examples: - '2023-06-05T00:00:00Z' termination_reason: anyOf: - type: string - type: 'null' title: Termination Reason description: The employee's termination reason. examples: - >- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. avatar: anyOf: - type: string - type: 'null' title: Avatar description: The URL of the employee's avatar image. examples: - http://alturl.com/h2h8m payroll_run_calendar: anyOf: - {} - type: 'null' title: Payroll Run Calendar description: The employee's payroll calendar examples: - 018af1fe-1250-77c5-9fcd-4bca1e4568f4 type: object required: - id - remote_id - modified_at - custom_fields title: HrisEmployeeResponse ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError HrisAddress: properties: name: anyOf: - type: string - type: 'null' title: Name description: Name of the location examples: - UK-HO-London location: anyOf: - type: string - type: 'null' title: Location description: Location examples: - UK-HO-London street_1: anyOf: - type: string - type: 'null' title: Street 1 description: Street 1 examples: - '1011' street_2: anyOf: - type: string - type: 'null' title: Street 2 description: Street 2 examples: - Lane number 4, Golden Villa city: anyOf: - type: string - type: 'null' title: City description: City examples: - London state: anyOf: - type: string - type: 'null' title: State description: State examples: - LND postal_code: anyOf: - type: string - type: 'null' title: Postal Code description: Postal Code examples: - '56273' country: anyOf: - type: string - type: 'null' title: Country description: Country examples: - UK type: object title: HrisAddress securitySchemes: HTTPBearer: type: http scheme: bearer ````