Bindbee Employees API
Normalized employee records from connected HRIS systems, including employment, compensation, benefits, groups and reporting hierarchy.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/bindbee-employees-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.1.0
info:
title: Bindbee Employees API
description: Employee records from connected HRIS systems Operations copied verbatim from the Bindbee unified API contract
published at https://api.bindbee.dev/openapi.json.
version: 0.1.0
contact:
name: Bindbee Support
email: support@bindbee.dev
url: https://docs.bindbee.dev/
servers:
- url: https://api.bindbee.dev
description: Bindbee global API
- url: https://api-eu.bindbee.dev
description: Bindbee EU API
tags:
- name: Employee
description: Employee records from connected HRIS systems
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
security:
- HTTPBearer: []
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:
anyOf:
- type: string
- type: 'null'
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:
anyOf:
- type: string
- type: 'null'
description: If provided, will only return employees with this employment status. Along with the standard values,
any connector specific value returned in the response can be passed as well.
examples:
- ACTIVE
- PENDING
- INACTIVE
- ACTIVE_EXTERNAL
- INACTIVE_EXTERNAL
- '-'
- LEAVE
- DECEASED
- RETIRED
title: Employment Status
description: If provided, will only return employees with this employment status. Along with the standard values,
any connector specific value returned in the response can be passed as well.
- name: employee_number
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
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: first_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: If provided, will only return employees with this first name (case-insensitive)
examples:
- Jane
title: First Name
description: If provided, will only return employees with this first name (case-insensitive)
- name: last_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: If provided, will only return employees with this last name (case-insensitive)
examples:
- Doe
title: Last Name
description: If provided, will only return employees with this last name (case-insensitive)
- name: work_email
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: If provided, will only return employees with this work email (case-insensitive)
examples:
- jane.doe@acme.com
title: Work Email
description: If provided, will only return employees with this work email (case-insensitive)
- 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: work_locations
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The ID of locations to fetch employees for
examples:
- 01931edf-04b6-7391-8a5c-93ac4b395316,01931edf-04c8-7649-a470-d85f6161bd1a
title: Work Locations
description: The ID of locations 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:
anyOf:
- type: string
- type: 'null'
description: The pagination cursor value.
title: Cursor
description: The pagination cursor value.
- name: modified_after
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'If provided, only objects synced by Bindbee after this date time will be returned. Format: DateTime
(ISO 8601). If no timezone offset is supplied, the value is interpreted as UTC.'
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). If no timezone offset is supplied, the value is interpreted as UTC.'
- name: expand
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
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'
'401':
description: Missing or invalid bearer authentication credentials.
headers:
WWW-Authenticate:
description: Bearer authentication challenge.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on
a different API category or a model whose writes are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the current window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
tags:
- Employee
summary: Create Employee
description: Creates an Employee object with the given values.
operationId: create_employee_api_hris_v1_employees_post
security:
- HTTPBearer: []
parameters:
- name: x-idempotency-key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Key to guarantee idempotent write execution.
title: X-Idempotency-Key
description: Key to guarantee idempotent write execution.
- name: x-connector-token
in: header
required: true
schema:
type: string
title: X-Connector-Token
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'401':
description: Missing or invalid bearer authentication credentials.
headers:
WWW-Authenticate:
description: Bearer authentication challenge.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on
a different API category or a model whose writes are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the current window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/hris/v1/employees/create/meta:
get:
tags:
- Employee
summary: Get Create Employee Request Body
description: Returns the data points required to add new employee in HRIS
operationId: get_create_employee_request_body_api_hris_v1_employees_create_meta_get
security:
- HTTPBearer: []
parameters:
- 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/MetaApiResponseModel'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'401':
description: Missing or invalid bearer authentication credentials.
headers:
WWW-Authenticate:
description: Bearer authentication challenge.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on
a different API category or a model whose writes are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the current window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/hris/v1/employees/meta/post:
get:
tags:
- Employee
summary: Get Create Employee Meta
description: Returns request schema for POST Employee request.
operationId: get_create_employee_meta_api_hris_v1_employees_meta_post_get
security:
- HTTPBearer: []
parameters:
- name: x-connector-token
in: header
required: true
schema:
type: string
title: X-Connector-Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- type: object
additionalProperties: true
- $ref: '#/components/schemas/MetaApiResponseModel'
title: Response Get Create Employee Meta Api Hris V1 Employees Meta Post Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'401':
description: Missing or invalid bearer authentication credentials.
headers:
WWW-Authenticate:
description: Bearer authentication challenge.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on
a different API category or a model whose writes are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the current window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/hris/v1/employees/{id}:
get:
tags:
- Employee
summary: Get Employee By Id
description: Returns an Employee object with the given id.
operationId: get_employee_by_id_api_hris_v1_employees__id__get
security:
- HTTPBearer: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
title: Id
- 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: expand
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
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/HrisEmployeeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'401':
description: Missing or invalid bearer authentication credentials.
headers:
WWW-Authenticate:
description: Bearer authentication challenge.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on
a different API category or a model whose writes are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum requests allowed in the current window.
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
schema:
type: integer
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
schemas:
ErrorResponse:
type: object
required:
- detail
properties:
detail:
type: string
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
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
format: date-time
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
work_locations:
anyOf:
- items: {}
type: array
- type: 'null'
title: Work Locations
description: The IDs of the work locations that the employee belongs to.
examples:
- - 018af1fe-1250-772d-87c5-6f725a579e8a
- 018af1fe-1250-772d-87c5-6f725a579e8b
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: Ge
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bindbee/refs/heads/main/openapi/bindbee-employees-api-openapi.yml