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": "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"
}
}
'import requests
url = "https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees"
payload = {
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees"
payload := strings.NewReader("{\n \"email\": \"john.smith@example.com\",\n \"legalId\": \"12345678Z\",\n \"name\": \"John\",\n \"surname\": \"Smith\",\n \"birthDate\": \"1985-07-15\",\n \"grossSalary\": {\n \"amountInCents\": 4500000,\n \"currency\": \"EUR\"\n },\n \"hiringDate\": \"2023-01-10\",\n \"taxRegime\": \"general\",\n \"workdayConfiguration\": {\n \"daysPerMonth\": 22,\n \"workTimePercentage\": 100,\n \"numberOfPaychecks\": 14,\n \"collectiveAgreementSalary\": {\n \"amountInCents\": 3800000,\n \"currency\": \"EUR\"\n }\n },\n \"internalId\": \"EMP-1234\",\n \"costCenter\": \"Finance\",\n \"payrollCompany\": \"Main Branch\",\n \"modelId\": \"7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7\",\n \"metadata\": {\n \"department\": \"Finance\",\n \"manager\": \"Jane Doe\",\n \"office\": \"Madrid\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"john.smith@example.com\",\n \"legalId\": \"12345678Z\",\n \"name\": \"John\",\n \"surname\": \"Smith\",\n \"birthDate\": \"1985-07-15\",\n \"grossSalary\": {\n \"amountInCents\": 4500000,\n \"currency\": \"EUR\"\n },\n \"hiringDate\": \"2023-01-10\",\n \"taxRegime\": \"general\",\n \"workdayConfiguration\": {\n \"daysPerMonth\": 22,\n \"workTimePercentage\": 100,\n \"numberOfPaychecks\": 14,\n \"collectiveAgreementSalary\": {\n \"amountInCents\": 3800000,\n \"currency\": \"EUR\"\n }\n },\n \"internalId\": \"EMP-1234\",\n \"costCenter\": \"Finance\",\n \"payrollCompany\": \"Main Branch\",\n \"modelId\": \"7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7\",\n \"metadata\": {\n \"department\": \"Finance\",\n \"manager\": \"Jane Doe\",\n \"office\": \"Madrid\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"john.smith@example.com\",\n \"legalId\": \"12345678Z\",\n \"name\": \"John\",\n \"surname\": \"Smith\",\n \"birthDate\": \"1985-07-15\",\n \"grossSalary\": {\n \"amountInCents\": 4500000,\n \"currency\": \"EUR\"\n },\n \"hiringDate\": \"2023-01-10\",\n \"taxRegime\": \"general\",\n \"workdayConfiguration\": {\n \"daysPerMonth\": 22,\n \"workTimePercentage\": 100,\n \"numberOfPaychecks\": 14,\n \"collectiveAgreementSalary\": {\n \"amountInCents\": 3800000,\n \"currency\": \"EUR\"\n }\n },\n \"internalId\": \"EMP-1234\",\n \"costCenter\": \"Finance\",\n \"payrollCompany\": \"Main Branch\",\n \"modelId\": \"7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7\",\n \"metadata\": {\n \"department\": \"Finance\",\n \"manager\": \"Jane Doe\",\n \"office\": \"Madrid\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8"
}{
"message": "Invalid request: 'email' field is required"
}{
"message": "Invalid API key"
}{
"message": "Your API key does not have permission to register employees"
}{
"message": "Company with ID 'a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890' not found"
}{
"message": "There is already an existing employee with the same data"
}{
"message": "Internal server error: Unable to process request"
}Employees
Register employee
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": "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"
}
}
'import requests
url = "https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees"
payload = {
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees"
payload := strings.NewReader("{\n \"email\": \"john.smith@example.com\",\n \"legalId\": \"12345678Z\",\n \"name\": \"John\",\n \"surname\": \"Smith\",\n \"birthDate\": \"1985-07-15\",\n \"grossSalary\": {\n \"amountInCents\": 4500000,\n \"currency\": \"EUR\"\n },\n \"hiringDate\": \"2023-01-10\",\n \"taxRegime\": \"general\",\n \"workdayConfiguration\": {\n \"daysPerMonth\": 22,\n \"workTimePercentage\": 100,\n \"numberOfPaychecks\": 14,\n \"collectiveAgreementSalary\": {\n \"amountInCents\": 3800000,\n \"currency\": \"EUR\"\n }\n },\n \"internalId\": \"EMP-1234\",\n \"costCenter\": \"Finance\",\n \"payrollCompany\": \"Main Branch\",\n \"modelId\": \"7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7\",\n \"metadata\": {\n \"department\": \"Finance\",\n \"manager\": \"Jane Doe\",\n \"office\": \"Madrid\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"john.smith@example.com\",\n \"legalId\": \"12345678Z\",\n \"name\": \"John\",\n \"surname\": \"Smith\",\n \"birthDate\": \"1985-07-15\",\n \"grossSalary\": {\n \"amountInCents\": 4500000,\n \"currency\": \"EUR\"\n },\n \"hiringDate\": \"2023-01-10\",\n \"taxRegime\": \"general\",\n \"workdayConfiguration\": {\n \"daysPerMonth\": 22,\n \"workTimePercentage\": 100,\n \"numberOfPaychecks\": 14,\n \"collectiveAgreementSalary\": {\n \"amountInCents\": 3800000,\n \"currency\": \"EUR\"\n }\n },\n \"internalId\": \"EMP-1234\",\n \"costCenter\": \"Finance\",\n \"payrollCompany\": \"Main Branch\",\n \"modelId\": \"7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7\",\n \"metadata\": {\n \"department\": \"Finance\",\n \"manager\": \"Jane Doe\",\n \"office\": \"Madrid\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pre-public-api.cobee.io/api/v3/companies/{companyId}/employees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"john.smith@example.com\",\n \"legalId\": \"12345678Z\",\n \"name\": \"John\",\n \"surname\": \"Smith\",\n \"birthDate\": \"1985-07-15\",\n \"grossSalary\": {\n \"amountInCents\": 4500000,\n \"currency\": \"EUR\"\n },\n \"hiringDate\": \"2023-01-10\",\n \"taxRegime\": \"general\",\n \"workdayConfiguration\": {\n \"daysPerMonth\": 22,\n \"workTimePercentage\": 100,\n \"numberOfPaychecks\": 14,\n \"collectiveAgreementSalary\": {\n \"amountInCents\": 3800000,\n \"currency\": \"EUR\"\n }\n },\n \"internalId\": \"EMP-1234\",\n \"costCenter\": \"Finance\",\n \"payrollCompany\": \"Main Branch\",\n \"modelId\": \"7a6c9ab8-8c2d-5c82-9c8c-f5e7e7e7e7e7\",\n \"metadata\": {\n \"department\": \"Finance\",\n \"manager\": \"Jane Doe\",\n \"office\": \"Madrid\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "7f4c9ba8-9c2d-4b82-8b8c-e5f8f8f8f8f8"
}{
"message": "Invalid request: 'email' field is required"
}{
"message": "Invalid API key"
}{
"message": "Your API key does not have permission to register employees"
}{
"message": "Company with ID 'a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890' not found"
}{
"message": "There is already an existing employee with the same data"
}{
"message": "Internal server error: Unable to process request"
}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 underworkdayConfiguration:
daysPerMonth: 20numberOfPaychecks: 14
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The unique identifier of the company
Body
application/json
Employee data to be registered
The employee's email address
The employee's legal identifier
The employee's first name
The employee's surname
The employee's date of birth in ISO 8601 format (YYYY-MM-DD)
The employee's gross salary details
Show child attributes
Show child attributes
Example:
{
"amountInCents": 4500000,
"currency": "EUR"
}
The date when the employee was hired in ISO 8601 format (YYYY-MM-DD)
The employee's tax regime
Available options:
general, basque, navarrese, biscayan Configuration of the employee's workday
Show child attributes
Show child attributes
Example:
{
"daysPerMonth": 22,
"workTimePercentage": 100,
"numberOfPaychecks": 14,
"collectiveAgreementSalary": {
"amountInCents": 3800000,
"currency": "EUR"
}
}
Your internal identifier for the employee
The cost centre associated with this employee
The company handling the employee's payroll, if different from the main company
The ID of the benefit model to assign to this employee
Additional metadata for the employee (key-value pairs)
Response
Employee successfully registered
The unique identifier of the registered employee