Add an employee
curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/employees \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Jorge Ruiz Gómez",
"start_date": "2026-11-02",
"external_id": "emp_10442",
"tax_id": "12345678Z",
"social_security_number": "281234567840",
"birth_date": "1991-04-18",
"employment": {
"contract_type": "100",
"contribution_group": 5,
"occupation_code": "3820",
"working_time_coefficient": 1000,
"contribution_account": "28123456789"
}
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/employees"
payload = {
"name": "Jorge Ruiz Gómez",
"start_date": "2026-11-02",
"external_id": "emp_10442",
"tax_id": "12345678Z",
"social_security_number": "281234567840",
"birth_date": "1991-04-18",
"employment": {
"contract_type": "100",
"contribution_group": 5,
"occupation_code": "3820",
"working_time_coefficient": 1000,
"contribution_account": "28123456789"
}
}
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({
name: 'Jorge Ruiz Gómez',
start_date: '2026-11-02',
external_id: 'emp_10442',
tax_id: '12345678Z',
social_security_number: '281234567840',
birth_date: '1991-04-18',
employment: {
contract_type: '100',
contribution_group: 5,
occupation_code: '3820',
working_time_coefficient: 1000,
contribution_account: '28123456789'
}
})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"start_date": "2023-12-25",
"details": {},
"active": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"external_id": "<string>",
"tax_id": "<string>",
"social_security_number": "<string>",
"birth_date": "2023-12-25",
"employment": {
"contribution_account": "<string>",
"contract_type": "<string>",
"working_time_coefficient": 500,
"contribution_group": 6,
"occupation_code": "<string>",
"collective_agreement": "<string>"
}
}{
"error": "lines[0].vat_rate must be 21, 10, 4 or 0",
"code": "invalid_invoice",
"request_id": "req_01JAB3K9X2"
}{
"error": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "Review and approve in the authenticated web application",
"code": "person_required",
"request_id": "req_01JAB3K9X2"
}Employees
Add an employee
Adds an employee to the company.
POST
/
companies
/
{company_id}
/
employees
Add an employee
curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/employees \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Jorge Ruiz Gómez",
"start_date": "2026-11-02",
"external_id": "emp_10442",
"tax_id": "12345678Z",
"social_security_number": "281234567840",
"birth_date": "1991-04-18",
"employment": {
"contract_type": "100",
"contribution_group": 5,
"occupation_code": "3820",
"working_time_coefficient": 1000,
"contribution_account": "28123456789"
}
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/employees"
payload = {
"name": "Jorge Ruiz Gómez",
"start_date": "2026-11-02",
"external_id": "emp_10442",
"tax_id": "12345678Z",
"social_security_number": "281234567840",
"birth_date": "1991-04-18",
"employment": {
"contract_type": "100",
"contribution_group": 5,
"occupation_code": "3820",
"working_time_coefficient": 1000,
"contribution_account": "28123456789"
}
}
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({
name: 'Jorge Ruiz Gómez',
start_date: '2026-11-02',
external_id: 'emp_10442',
tax_id: '12345678Z',
social_security_number: '281234567840',
birth_date: '1991-04-18',
employment: {
contract_type: '100',
contribution_group: 5,
occupation_code: '3820',
working_time_coefficient: 1000,
contribution_account: '28123456789'
}
})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"start_date": "2023-12-25",
"details": {},
"active": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"external_id": "<string>",
"tax_id": "<string>",
"social_security_number": "<string>",
"birth_date": "2023-12-25",
"employment": {
"contribution_account": "<string>",
"contract_type": "<string>",
"working_time_coefficient": 500,
"contribution_group": 6,
"occupation_code": "<string>",
"collective_agreement": "<string>"
}
}{
"error": "lines[0].vat_rate must be 21, 10, 4 or 0",
"code": "invalid_invoice",
"request_id": "req_01JAB3K9X2"
}{
"error": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "Review and approve in the authenticated web application",
"code": "person_required",
"request_id": "req_01JAB3K9X2"
}Live capability. Melso runs this in production today. Partner keys reach it once your partner account is enabled. See Availability.
name, start_date and details are
live today. The structured identity and employment fields are preview:
they are what affiliation, payroll runs and SEPE notifications use.Authorizations
Your partner secret key, mk_live_… for real companies or mk_test_…
for test companies. Keep it on your servers. See
Authentication.
Headers
A unique key, such as a UUID, that makes a retried create safe. Reusing a key with a different body is refused.
Maximum string length:
255Path Parameters
The company's ID. Every company-scoped call works in exactly this company.
Body
application/json
Required string length:
1 - 200Free-form notes for Melso's team, such as the job and salary agreed.
Preview. Your ID for the employee.
Preview. DNI or NIE.
Preview. The número de afiliación (NAF)
Preview.
Preview. What the TGSS and the SEPE need about the job.
Show child attributes
Show child attributes
Response
The employee.
Preview.
Preview.
Preview.
Preview.
Preview. What the TGSS and the SEPE need about the job.
Show child attributes
Show child attributes