Submit a payroll run

curl --request POST \
  --url https://api.melso.ai/v1/companies/{company_id}/payroll-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "period": "2026-10",
  "kind": "ordinary",
  "payment_date": "2026-10-31",
  "external_id": "run_2026_10",
  "payslips": [
    {
      "employee_id": "6a1f0c2e-4b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "days_contributed": 31,
      "gross_pay": "2450.00",
      "in_kind_pay": "0.00",
      "irpf": {
        "base": "2450.00",
        "rate": "14.20",
        "withheld": "347.90"
      },
      "social_security": {
        "base_common_contingencies": "2654.17",
        "base_professional_contingencies": "2654.17",
        "employee_contribution": "172.79"
      },
      "concepts": [
        {
          "code": "salario_base",
          "description": "Salario base",
          "amount": "1900.00",
          "kind": "salary"
        },
        {
          "code": "plus_transporte",
          "description": "Plus transporte",
          "amount": "150.00",
          "kind": "non_salary"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.melso.ai/v1/companies/{company_id}/payroll-runs"

payload = {
    "period": "2026-10",
    "kind": "ordinary",
    "payment_date": "2026-10-31",
    "external_id": "run_2026_10",
    "payslips": [
        {
            "employee_id": "6a1f0c2e-4b3d-4e5f-8a9b-0c1d2e3f4a5b",
            "days_contributed": 31,
            "gross_pay": "2450.00",
            "in_kind_pay": "0.00",
            "irpf": {
                "base": "2450.00",
                "rate": "14.20",
                "withheld": "347.90"
            },
            "social_security": {
                "base_common_contingencies": "2654.17",
                "base_professional_contingencies": "2654.17",
                "employee_contribution": "172.79"
            },
            "concepts": [
                {
                    "code": "salario_base",
                    "description": "Salario base",
                    "amount": "1900.00",
                    "kind": "salary"
                },
                {
                    "code": "plus_transporte",
                    "description": "Plus transporte",
                    "amount": "150.00",
                    "kind": "non_salary"
                }
            ]
        }
    ]
}
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({
    period: '2026-10',
    kind: 'ordinary',
    payment_date: '2026-10-31',
    external_id: 'run_2026_10',
    payslips: [
      {
        employee_id: '6a1f0c2e-4b3d-4e5f-8a9b-0c1d2e3f4a5b',
        days_contributed: 31,
        gross_pay: '2450.00',
        in_kind_pay: '0.00',
        irpf: {base: '2450.00', rate: '14.20', withheld: '347.90'},
        social_security: {
          base_common_contingencies: '2654.17',
          base_professional_contingencies: '2654.17',
          employee_contribution: '172.79'
        },
        concepts: [
          {
            code: 'salario_base',
            description: 'Salario base',
            amount: '1900.00',
            kind: 'salary'
          },
          {
            code: 'plus_transporte',
            description: 'Plus transporte',
            amount: '150.00',
            kind: 'non_salary'
          }
        ]
      }
    ]
  })
};

fetch('https://api.melso.ai/v1/companies/{company_id}/payroll-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "period": "<string>",
  "kind": "ordinary",
  "status": "received",
  "created_at": "2023-11-07T05:31:56Z",
  "external_id": "<string>",
  "totals": {
    "employees": 123,
    "gross_pay": "121.00",
    "irpf_withheld": "121.00",
    "employee_contributions": "121.00"
  },
  "issues": [
    {
      "employee_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "code": "<string>",
      "message": "<string>",
      "blocking": true
    }
  ],
  "settlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tax_return_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

{
  "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"
}

{
  "error": "The tax return changed or is not ready for approval",
  "code": "version_conflict",
  "request_id": "req_01JAB3K9X2"
}

POST

companies

{company_id}

payroll-runs

Submit a payroll run

curl --request POST \
  --url https://api.melso.ai/v1/companies/{company_id}/payroll-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "period": "2026-10",
  "kind": "ordinary",
  "payment_date": "2026-10-31",
  "external_id": "run_2026_10",
  "payslips": [
    {
      "employee_id": "6a1f0c2e-4b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "days_contributed": 31,
      "gross_pay": "2450.00",
      "in_kind_pay": "0.00",
      "irpf": {
        "base": "2450.00",
        "rate": "14.20",
        "withheld": "347.90"
      },
      "social_security": {
        "base_common_contingencies": "2654.17",
        "base_professional_contingencies": "2654.17",
        "employee_contribution": "172.79"
      },
      "concepts": [
        {
          "code": "salario_base",
          "description": "Salario base",
          "amount": "1900.00",
          "kind": "salary"
        },
        {
          "code": "plus_transporte",
          "description": "Plus transporte",
          "amount": "150.00",
          "kind": "non_salary"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.melso.ai/v1/companies/{company_id}/payroll-runs"

payload = {
    "period": "2026-10",
    "kind": "ordinary",
    "payment_date": "2026-10-31",
    "external_id": "run_2026_10",
    "payslips": [
        {
            "employee_id": "6a1f0c2e-4b3d-4e5f-8a9b-0c1d2e3f4a5b",
            "days_contributed": 31,
            "gross_pay": "2450.00",
            "in_kind_pay": "0.00",
            "irpf": {
                "base": "2450.00",
                "rate": "14.20",
                "withheld": "347.90"
            },
            "social_security": {
                "base_common_contingencies": "2654.17",
                "base_professional_contingencies": "2654.17",
                "employee_contribution": "172.79"
            },
            "concepts": [
                {
                    "code": "salario_base",
                    "description": "Salario base",
                    "amount": "1900.00",
                    "kind": "salary"
                },
                {
                    "code": "plus_transporte",
                    "description": "Plus transporte",
                    "amount": "150.00",
                    "kind": "non_salary"
                }
            ]
        }
    ]
}
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({
    period: '2026-10',
    kind: 'ordinary',
    payment_date: '2026-10-31',
    external_id: 'run_2026_10',
    payslips: [
      {
        employee_id: '6a1f0c2e-4b3d-4e5f-8a9b-0c1d2e3f4a5b',
        days_contributed: 31,
        gross_pay: '2450.00',
        in_kind_pay: '0.00',
        irpf: {base: '2450.00', rate: '14.20', withheld: '347.90'},
        social_security: {
          base_common_contingencies: '2654.17',
          base_professional_contingencies: '2654.17',
          employee_contribution: '172.79'
        },
        concepts: [
          {
            code: 'salario_base',
            description: 'Salario base',
            amount: '1900.00',
            kind: 'salary'
          },
          {
            code: 'plus_transporte',
            description: 'Plus transporte',
            amount: '150.00',
            kind: 'non_salary'
          }
        ]
      }
    ]
  })
};

fetch('https://api.melso.ai/v1/companies/{company_id}/payroll-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "period": "<string>",
  "kind": "ordinary",
  "status": "received",
  "created_at": "2023-11-07T05:31:56Z",
  "external_id": "<string>",
  "totals": {
    "employees": 123,
    "gross_pay": "121.00",
    "irpf_withheld": "121.00",
    "employee_contributions": "121.00"
  },
  "issues": [
    {
      "employee_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "code": "<string>",
      "message": "<string>",
      "blocking": true
    }
  ],
  "settlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tax_return_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

{
  "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"
}

{
  "error": "The tax return changed or is not ready for approval",
  "code": "version_conflict",
  "request_id": "req_01JAB3K9X2"
}

Preview. A contract we are building with design partners. It is not callable yet, and fields can still change. See Availability.

Melso does not recalculate the payslips. It validates them against each employee’s affiliation and contribution bases, then uses them for three things:

the month’s Social Security contribution settlement (liquidación directa) and its CRA data,
the work-income boxes of the modelo 111, and the employee records (key A) of the year’s modelo 190,
each employee’s annual withholding certificate.

Send a second run with kind supplementary for arrears or late corrections of an earlier month.

Authorizations

Authorization

string

header

required

Your partner secret key, mk_live_… for real companies or mk_test_… for test companies. Keep it on your servers. See Authentication.

Headers

Idempotency-Key

string

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: 255

Path Parameters

company_id

string<uuid>

required

The company's ID. Every company-scoped call works in exactly this company.

Body

application/json

period

string

required

The month the pay accrues to, such as 2026-10.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$

kind

enum<string>

required

extra for a paga extraordinaria paid apart; supplementary for arrears or a correction of an earlier month.

Available options:

ordinary,

extra,

supplementary

payment_date

string<date>

required

payslips

object[]

required

Minimum array length: 1

Show child attributes

external_id

string

Your ID for the run.

Response

The run, received. Validation results arrive in issues and with the payroll_run.validated event.

string<uuid>

required

period

string

required

kind

enum<string>

required

Available options:

ordinary,

extra,

supplementary

status

enum<string>

required

validated: usable for the settlement and the returns. rejected: see issues. settled: the month's contribution settlement is confirmed.

Available options:

received,

validated,

rejected,

settled

created_at

string<date-time>

required

external_id

string | null

totals

object

Show child attributes

issues

object[]

Show child attributes

settlement_id

string<uuid> | null

tax_return_ids

string<uuid>[]

The 111 (and, in January, the 190) this run feeds.

Get started

Solutions

Companies and access

Invoicing

Bookkeeping

Taxes

Payroll and Social Security

Submit a payroll run

Authorizations

Headers

Path Parameters

Body

Response