curl --request GET \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}', 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": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}Get a tax return
Returns one return with its boxes, the records behind an informative return and what to review before approving.
curl --request GET \
--url https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.melso.ai/v1/companies/{company_id}/tax-returns/{tax_return_id}', 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": "invalid token",
"code": "unauthorized",
"request_id": "req_01JAB3K9X2"
}{
"error": "invoice not found",
"code": "not_found",
"request_id": "req_01JAB3K9X2"
}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.
Response
The return.
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.