curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}/mark-filed \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expected_version": 2
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}/mark-filed"
payload = { "expected_version": 2 }
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({expected_version: 2})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}/mark-filed', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"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": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}{
"error": "The tax return changed or is not ready for approval",
"code": "version_conflict",
"request_id": "req_01JAB3K9X2"
}Mark a return as filed by the company
Records that the company filed this return by itself, at exactly expected_version, once its period has ended.
curl --request POST \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}/mark-filed \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"expected_version": 2
}
'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}/mark-filed"
payload = { "expected_version": 2 }
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({expected_version: 2})
};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}/mark-filed', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"model": "<string>",
"period": "2026-Q3",
"status": "draft",
"is_estimate": true,
"amount": "121.00",
"version": 123,
"approved_version": 123,
"approved_at": "2023-11-07T05:31:56Z",
"deadline": "2023-12-25",
"direct_debit_deadline": "2023-12-25",
"boxes": [
{
"box": "<string>",
"key": "<string>",
"amount": "121.00"
}
],
"records": [
{
"tax_id": "<string>",
"name": "<string>",
"country": "<string>",
"key": "<string>",
"amount": "121.00",
"withheld": "121.00",
"quarters": [
"121.00"
],
"missing": [
"tax_id"
]
}
],
"review": [
"missing_tax_id"
],
"unconfirmed_expenses": 123,
"filed_at": "2023-11-07T05:31:56Z",
"filing": {
"filed_at": "2023-11-07T05:31:56Z",
"reference": "<string>",
"csv": "<string>",
"receipt": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"filename": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"url": "<string>"
},
"filed_by": "melso"
},
"recalculated": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"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": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}{
"error": "The tax return changed or is not ready for approval",
"code": "version_conflict",
"request_id": "req_01JAB3K9X2"
}filing.Authorizations
Your partner secret key, mk_live_… for real companies or mk_test_…
for test companies. Keep it on your servers. See
Authentication.
Path Parameters
The company's ID. Every company-scoped call works in exactly this company.
Body
x >= 1Response
The return, filed.
The return's UUID, or estimate:<model>:<period> for an estimate.
The form. Melso calculates 303, 130, 111, 115, 190, 180, 347, 349 and 390 today; a reminder form marked filed has its own model.
A year (2026), a quarter (2026-Q3), a month (2026-09) or an instalment (2026-1P).
^[0-9]{4}(-Q[1-4]|-(0[1-9]|1[0-2])|-[1-3]P)?$"2026-Q3"
draft: calculated, still recalculated from the records. approved: the owner authorized this exact version. filed: filed, with the administration's reference and receipt when Melso filed it.
draft, approved, filed An estimate has an amount only. It has no boxes, no version and no approval.
The result. Negative to offset or refund (303); 0.00 for an informative return.
^-?[0-9]+\.[0-9]{2}$"121.00"
Raised on every recalculation that changes the draft. Approval needs the exact version.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
What to check before approving.
missing_tax_id, cadastral_reference, eu_key_assumed, rates_assumed, volume_split Expenses in the return that are not yet confirmed as deductible.
Preview. The administration's evidence, when Melso filed the return.
Show child attributes
Show child attributes
For a filed return whose records changed afterwards, what it would be today. A difference may need a complementary or corrective return.