Skip to main content
POST
/
companies
/
{companyId}
/
employees
Register employee
curl --request POST \
  --url https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[email protected]",
  "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"
  }
}
'
{
  "id": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8"
}

​
Overview

This endpoint allows you to register a new employee in the Cobee system. When an employee is successfully registered through this endpoint, the system automatically sends an invitation to the employee’s email address. The employee must complete the corresponding onboarding process by activating the link sent to their email. Therefore, it is crucial to provide a correct email address if you want the employee to be able to access their Cobee account.
Important: Always ensure the email address is valid and belongs to the employee. An incorrect email address will prevent the employee from completing the onboarding process and accessing their benefits.
Note: For part-time employees, if you provide a working time percentage lower than 100%, please note that their benefit limits will be adjusted proportionally. It is important to ensure that the salary you provide is already adjusted to reflect the employee’s part-time status (i.e., the actual salary they will receive, not the full-time equivalent).
Note: The employee will automatically receive an invitation email to activate their account. If the invitation expires or there is an error, use the Invite employee endpoint to resend the invitation.
Defaults: If omitted in the request body, the following default values are applied under workdayConfiguration:
  • daysPerMonth: 20
  • numberOfPaychecks: 14

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
companyId
string<uuid>
required

The unique identifier of the company

Body

application/json

Employee data to be registered

​
email
string<email>
required

The employee's email address

​
legalId
string
required

The employee's legal identifier

​
name
string
required

The employee's first name

​
surname
string
required

The employee's surname

​
birthDate
string<date>
required

The employee's date of birth in ISO 8601 format (YYYY-MM-DD)

​
grossSalary
object
required

The employee's gross salary details

Example:
{
  "amountInCents": 4500000,
  "currency": "EUR"
}
​
hiringDate
string<date>
required

The date when the employee was hired in ISO 8601 format (YYYY-MM-DD)

​
taxRegime
enum<string>
required

The employee's tax regime

Available options:
general,
basque,
navarrese,
biscayan
​
workdayConfiguration
object
required

Configuration of the employee's workday

Example:
{
  "daysPerMonth": 22,
  "workTimePercentage": 100,
  "numberOfPaychecks": 14,
  "collectiveAgreementSalary": {
    "amountInCents": 3800000,
    "currency": "EUR"
  }
}
​
internalId
string

Your internal identifier for the employee

​
costCenter
string

The cost centre associated with this employee

​
payrollCompany
string

The company handling the employee's payroll, if different from the main company

​
modelId
string<uuid>

The ID of the benefit model to assign to this employee

​
metadata
object

Additional metadata for the employee (key-value pairs)

Response

Employee successfully registered

​
id
string<uuid>
required

The unique identifier of the registered employee