Cobee by Pluxee Companies API
The Companies API from Cobee by Pluxee — 16 operation(s) for companies.
OpenAPI Specification
openapi: 3.0.1
info:
title: Public Companies API
description: Public API definition where you can check the documentation for the different available operations to integrate with the platform.
license:
name: MIT
version: 1.0.0
servers:
- url: https://pre-public-api.cobee.io/api/v3
- url: https://public-api.cobee.io/api/v3
security:
- bearerAuth: []
tags:
- name: Companies
paths:
/companies/{companyId}/employees/{employeeId}/limits:
put:
summary: Set employee limits
description: Sets the employee limits for all the benefits defined by the partner
parameters:
- name: companyId
in: path
required: true
schema:
type: string
format: uuid
description: The company identifier
- name: employeeId
in: path
required: true
schema:
type: string
format: uuid
description: The employee identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
meal:
type: object
required:
- amount
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
currency:
type: string
transport:
type: object
required:
- amount
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
currency:
type: string
nursery:
type: object
required:
- amount
properties:
amount:
type: object
required:
- amountInCents
- currency
properties:
amountInCents:
type: integer
currency:
type: string
responses:
'200':
description: Limits successfully set
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Invalid employeeId
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: invalid_token
'403':
description: Forbidden - Company does not belong to the specified partner
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Company does not belong to the specified partner
tags:
- Companies
/companies:
get:
summary: Get all companies associated with the authenticated user
parameters:
- name: legalId
in: query
required: false
description: Company CIF(s) to filter by. Can be a single CIF or multiple CIFs separated by commas
schema:
oneOf:
- type: string
- type: array
items:
type: string
example: B12345678,B87654321
- name: state
in: query
required: false
description: Company state to filter by
schema:
type: string
enum:
- active
example: active
responses:
'200':
description: New response
content:
application/json:
schema:
type: object
properties:
companies:
type: array
items:
$ref: '#/components/schemas/Company'
'401':
description: Unauthorised - Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthorized
tags:
- Companies
/companies/{companyId}/employees:
post:
summary: Register employee
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
requestBody:
description: Employee data to be registered
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterEmployeeRequest'
example:
email: john.smith@example.com
legalId: 12345678Z
name: John
surname: Smith
birthDate: '1985-07-15'
grossSalary:
amountInCents: 4500000
currency: EUR
hiringDate: '2023-01-10'
taxRegime: general
workdayConfiguration:
daysPerMonth: 22
workTimePercentage: 100
numberOfPaychecks: 14
collectiveAgreementSalary:
amountInCents: 3800000
currency: EUR
internalId: EMP-1234
costCenter: Finance
payrollCompany: Main Branch
modelId: 7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7
metadata:
department: Finance
manager: Jane Doe
office: Madrid
responses:
'201':
description: Employee successfully registered
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterEmployeeResponse'
example:
id: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
'400':
description: Bad Request - The request body is invalid or missing required fields
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: 'Invalid request: ''email'' field is required'
'401':
description: Unauthorised - Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Invalid API key
'403':
description: Forbidden - You don't have permission to register employees
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Your API key does not have permission to register employees
'404':
description: Not Found - The company ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Company with ID 'a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890' not found
'409':
description: Conflict - An employee with the same email or legal ID already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: An employee with email 'john.smith@example.com' already exists
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: 'Internal server error: Unable to process request'
tags:
- Companies
get:
summary: Get employees
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: email
in: query
required: false
description: Employee email to filter by
schema:
type: string
format: email
example: john.smith@example.com
- name: legalId
in: query
required: false
description: Employee legal ID to filter by
schema:
type: string
example: 12345678Z
- name: internalId
in: query
required: false
description: Employee internal ID to filter by
schema:
type: string
example: EMP-1234
- name: state
in: query
required: false
description: Employee state to filter by
schema:
type: string
enum:
- not-active
- active
- removed
- blocked
example: active
responses:
'200':
description: Employees successfully retrieved
content:
application/json:
schema:
type: object
properties:
employees:
type: array
items:
$ref: '#/components/schemas/Employee'
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
/companies/{companyId}/employees/{employeeId}:
get:
summary: Get employee
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
responses:
'200':
description: Employee successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Employee'
example:
id: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
email: john.smith@example.com
legalId: 12345678Z
name: John
surname: Smith
birthDate: '1985-07-15'
grossSalary:
amountInCents: 4500000
currency: EUR
hiringDate: '2023-01-10'
taxRegime: general
workdayConfiguration:
daysPerMonth: 22
workTimePercentage: 100
numberOfPaychecks: 14
collectiveAgreementSalary:
amountInCents: 3800000
currency: EUR
internalId: EMP-1234
costCenter: Finance
payrollCompany: Main Branch
modelId: 7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7
metadata:
department: Finance
manager: Jane Doe
office: Madrid
state: active
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
delete:
summary: Remove employee
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
responses:
'204':
description: Employee successfully removed
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
patch:
summary: Update employee
description: This endpoint allows you to update an existing employee's information in the Cobee system. All fields in the request body are optional, so you only need to include the fields you want to update.
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
requestBody:
description: Employee data to be updated
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEmployeeRequest'
example:
email: john.smith.updated@example.com
name: John
surname: Smith
birthDate: '1985-07-15'
grossSalary:
amountInCents: 4500000
currency: EUR
hiringDate: '2023-01-10'
taxRegime: general
workdayConfiguration:
daysPerMonth: 22
workTimePercentage: 100
numberOfPaychecks: 14
collectiveAgreementSalary:
amountInCents: 3800000
currency: EUR
internalId: EMP-1234
costCenter: Finance
payrollCompany: Main Branch
metadata:
department: Finance
manager: Jane Doe
office: Madrid
responses:
'204':
description: Employee successfully updated
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
/companies/{companyId}/employees/{employeeId}/block:
patch:
summary: Block employee
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
responses:
'204':
description: Employee successfully blocked
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'409':
description: The employee cannot be blocked because they are not in a valid state
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee with invalid state removed
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
/companies/{companyId}/employees/{employeeId}/unblock:
patch:
summary: Unblock employee
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
responses:
'204':
description: Employee successfully unblocked
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'409':
description: The employee cannot be unblocked because they are not in a valid state
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee with invalid state active
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
/companies/{companyId}/employees/{employeeId}/restore:
patch:
summary: Restore employee
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
responses:
'204':
description: Employee successfully restored
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
/companies/{companyId}/employees/{employeeId}/invite:
post:
summary: Send invitation email to an employee
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
responses:
'201':
description: Invitation email sent successfully
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'409':
description: The employee has already been invited
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee with invalid state active
'422':
description: Malformed URL
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: employeeId does not match any of the allowed types
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
/companies/{companyId}/employees/{employeeId}/migrate:
post:
summary: Migrates an employee from one company to another within the same corporation
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: employeeId
in: path
required: true
description: The unique identifier of the employee
schema:
type: string
format: uuid
example: 7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8
requestBody:
description: Employee data neeeded for the new company
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MigrateEmployeeRequest'
responses:
'200':
description: The employee was already on the destination company. No migration was needed
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: The unique identifier of the employee
'201':
description: Employee migrated successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: The unique identifier of the employee
'404':
description: Not Found - The employee ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Employee not found
'422':
description: Malformed URL
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: employeeId does not match any of the allowed types
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
tags:
- Companies
/companies/{companyId}/payroll-cycles:
get:
summary: Get the payroll cycles of a company. A null value on the end date means that the cycle is currently open.
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
responses:
'200':
description: Payroll cycles successfully retrieved
content:
application/json:
schema:
type: object
properties:
payrollCycles:
description: List of the company Payroll Cycles
type: array
items:
type: object
required:
- id
- start
- end
- fiscalYear
- payrollMonth
properties:
id:
type: string
description: The unique identifier of the payroll cycle.
start:
type: integer
description: The start date for the payroll cycle, in timestamp format.
format: timestamp
example: 1672531200
end:
type: integer
nullable: true
description: The end date for the payroll cycle, in timestamp format. A Null value is returned if the cycle is currently open.
example: 1675123200
fiscalYear:
type: string
description: The fiscal year of the payroll cycle.
example: '2023'
payrollMonth:
type: string
description: The month of the payroll cycle in MM format (e.g., '03' for March).
pattern: ^[0-9]{2}$
example: '03'
'404':
description: Not Found - The company ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Company not found
tags:
- Companies
/companies/{companyId}/payroll-cycles/{payrollCycleId}:
post:
summary: Close the current payroll cycle and open a new one.
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: dfe4e8a9-ff19-4b3b-953a-2d64c6e88539
- name: payrollCycleId
in: path
required: true
description: The unique identifier of the payroll cycle
schema:
type: string
format: uuid
example: dfe4e8a9-ff19-4b3b-953a-2d64c6e88539
responses:
'200':
description: Payroll Cycle successfully closed
content:
application/json:
example:
message: Payroll Cycle successfully closed
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: 'Invalid request: ''payrollCycleId'' field is required'
'401':
description: Unauthorised - Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthorised
'404':
description: Not Found - The payroll cycle ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Payroll cycle not found
'409':
description: Payroll cycle already closed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Payroll cycle already closed
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: 'Internal server error: Unable to process request'
tags:
- Companies
/companies/{companyId}/benefit-models:
get:
deprecated: true
summary: Get all benefit models for a the company
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
responses:
'200':
description: List of benefit models successfully retrieved
content:
application/json:
schema:
type: object
required:
- benefitModels
properties:
benefitModels:
description: List of benefit models
type: array
items:
$ref: '#/components/schemas/BenefitModel'
'401':
description: Unauthorised - Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthorized
tags:
- Companies
/companies/{companyId}/benefit-models/{benefitModelId}:
get:
deprecated: true
summary: Get the information of a benefit model
parameters:
- name: companyId
in: path
required: true
description: The unique identifier of the company
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
- name: benefitModelId
in: path
required: true
description: The unique identifier of the benefit model
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890
responses:
'200':
description: Benefit model successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/BenefitModel'
'401':
description: Unauthorised - Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthorized
'404':
description: Not Found - The benefit model ID was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Benefit Model not found
'500':
description: Internal Server Error - Something went wrong on our end
content:
application/json:
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cobee/refs/heads/main/openapi/cobee-companies-api-openapi.yml